Graphics Archiiacture 



Texas 

Instruments 

TIGA-340™ interface 




so 

CO ■ 

so 


Texas Instruments Graphics Architecture 


User's Guide 



Graphics Products 




TIGA-340™ Interface 
Texas Instruments 
Graphics Architecture 
User’s Guide 


Tfxas 

Instruments 



IMPORTANT NOTICE 


Texas Instruments (Tl) reserves the right to make changes to or to discontinue 
any semiconductor product or service identified in this publication without notice. 
Tl advises its customers to obtain the latest version of the relevant Information 
to verify, before placing orders, that the information being relied upon is current. 

Tl warrants performance of its semiconductor products to current specifications 
in accordance with Tl’s standard warranty. Testing and other quality control tech¬ 
niques are utilized to the extent Tl deems necessary to support this warranty. Un¬ 
less mandated by government requirements, specific testing of all parameters of 
each device is not necessarily performed. 

Tl assumes no liability for Tl applications assistance, customer product design, 
software performance, or Infringement of patents or services described herein. 
Nor does Tl warrant or represent that license, either express or implied, is granted 
under any patent right, copyright, mask work right, or other intellectual property 
right of Tl covering or relating to any combination, machine, or process in which 
such semiconductor products or services might be or are used. 


TRADEMARKS 

TIGA and TIGA-340 are trademarks of Texas Instruments Incorporated. 

ADI and AutoCAD are trademarks of Autodesk Inc. 

DGIS is a trademark of Graphic Software Systems, Inc. 

GEM is a trademark of Digital Research Inc. 

MS-Windows, PM, MS-DOS, and CodeView are trademarks of Microsoft Corp. 
Macintosh is a trademark of Apple Computer Corp. 

NEC is a trademark of NEC Corp. 

PC-DOS and PGA are trademarks of IBM Corp. 

Sony is a trademark of Sony Corp. 



Preface 


Read This First 


How to Use This Manual 

This document contains the following chapters: 

Chapter 1 Introduction 

Introduces the TiGA-340 Interface, its features and architecture. 

Chapter 2 Getting Started 

Contains instructions to install TIG A on a PC and to run a demonstration pro¬ 
gram. 

Chapter 3 TIGA Application Interface 

Describes the application interface and lists all TIGA primitive instructions. 

Chapter 4 Extensibility Through the User Library 

Describes how to extend TIGA by adding your own functions; also describes 
the command processing entry points of the communication driver. 

Appendix A TIGA Data Structures 

Describes the data structures used in TIGA. 

Appendix B Graphics Output Primitives 

Describes the assumptions made and conventions adopted for the drawing 
primitives. 

Appendix C TIGA Reserved Symbols 

Describes the function names reserved for internal use of TIGA. 

Appendix D Porting Guide 

Describes the procedure to port TIGA to any TMS340-based graphics 
board. 

Appendix E Debugger Support for TIGA 

Contains the initial TIGA debugger routines. 

Appendix F Giossary 

Contains the definitions of TIGA-specific and TIGA-related terms and acro¬ 
nyms. 
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Related Documentation 

The following TMS34010 documents are available from Texas Instruments: 

□ TheTMS34010 C Compiler User’s Guide (literature number 
SPVU005) tells you how to use the TMS34010 C Compiler. This C com¬ 
piler accepts standard Kernighan and Ritchie C source code and pro¬ 
duces TMS34010 assembly language source code. We suggest that 
you use The C Programming Language book (by Brian W. Kernighan 
and Dennis M. Ritchie) as a companion to the TMS34010C Compiler 
User’s Guide. 

□ The TMS34010Assembly Language Tools User’s Guide (literature 
number SPVU004) describes common object file format, assembler di¬ 
rectives, macro language, and assembler, linker, archiver, simulator, 
and object format converter operation. 

Q The TMS34010 Data S/ieef (literature number SPVS002) contains the 
recommended operating conditions, eiectrical specifications, and tim¬ 
ing characteristics of the TMS34010. 

□ The TMS34010 User’s Guide (literature number SPVU001) discusses 
hardware aspects of the TMS34010, such as pin functions, architec¬ 
ture, stack operation, and interfaces, and contains the TMS34010 in¬ 
struction set. 

You may also find the foilowing documentation useful: 

Kernighan, Brian, and Dennis Ritchie. The C Programming Language. En¬ 
glewood Cliffs, New Jersey: Prentice-Hall,1978. 

Newman W.M., and R. F. Sproull. Principles of Interactive Computer Graph¬ 
ics. 2nd ed. New York: McGraw-Hill, 1979. 
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style and Symbol Conventions 

This document uses the following conventions: 

□ TIGA primitive function names are shown in bold face lettering. 

□ Parameters for the TIGA functions are shown in program font (Couri¬ 
er). For example, the TIGA function drawjine has parameters xi, 

yl, x2, y2. 

□ Program examples and filenames (example: tigalnk . exe) are shown 
in program font. Here is an example program: 

#includ.e <tiga.h> 

main() 

{ 

short module; 

/* initialize TIGA */ 

if (!set_videomode(TIGA, INIT)) 

{ 

printf("Fatal Error - TIGA not installedXn"); 
exit (0); 

} 

/* attempt to install module */ 
if ((module = install_rlm("EXAMPLE")) < 0 ) 

{ 

printf("Fatal Error - couldn't install Example RLM\n"); 

printf("Error code = %d\n", module); 
exit(0); 

} 

/* code to invoke the module functions */ 


set_videomode(PREVIOUS, INIT); 

} 

□ In syntax descriptions, the instruction, command, or directive is in a 
bold face font with parameters in italics. Portions of a syntax in bold 
face (including quote marks) should be entered as shown. Portions of 
a syntax in italics describe the type of information that you provide. 
Square brackets identify optional information: 

mg2tiga MG font TIGA font [ "facename”] 
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Chapter 1 


Introduction 



This user’s guide describes the TIGA-340™ (Texas Instruments Graphics 
Architecture), a software interface that standardizes communication be¬ 
tween application software and all TMS340 family-based hardware for IBM- 
compatible personal computers. TIGA divides tasks between the TMS340 
processor and the 80x86 host to improve application performance. 


Section Page 

1.1 Developer’s Kits. 1-2 

1.2 Features . 1-3 

1.3 Architecture. 1-4 

1.4 Extensibility. 1-6 


The TIGA interface standard simplifies the development of portable applica¬ 
tions and application drivers to the diverse range of TMS340-based sys¬ 
tems. TIGA can be extended so that software developers can customize 
TIGA-340to a specific application and so that hardware developers can pro¬ 
vide a simple interface to specific target features. 

TIGA contains a low-level communication interface designed so that other 
standards such as MS-Windows, Presentation Manager (PM), DGIS, GEM, 
CGI, and PGA, can run through the interface with no performance penalty. 
Essentially, TIGA replaces custom communication routines in other soft¬ 
ware interfaces with a single standard set of host-to-TMS340 communica¬ 
tion routines. 
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1.1 Developer’s Kits 

This user’s guide supports two basic TIGA deveioper’s kits, the Driver De¬ 
veloper’s Kit (DDK) and the Software Porting Kit (SPK). A third deveiop¬ 
er’s kit, the Software Developer’s Kit (SDK), includes the DDK as a sub¬ 
set. 

□ DDK: The Driver Developer’s Kit (Ti part number TMS340 DDK-PC) 

The TIGA-340 DDK provides software designers with the tools required 
to produce TIGA-compatible applications. These tools include a copy of 
the TIGA-340 interface, which runs on the TMS34010 Software Devel¬ 
opment Board, a user’s guide, utilities, an AutoCAD release 9 sample 
driver, and several TIGA-compatible example programs. With these 
tools a programmer can modify existing applications to run with the 
TIGA-340 interface or develop new TIGA-compatible applications. The 
development of TIGA-compatible applications is easy because the 
tools in the kit are designed to work with the industry-standard Microsoft 
C development tools and debugging environments. 

□ SPK: The Software Porting Kit (TI part number TMS340SPK-PC) 

The SPK helps hardware manufacturers and software operating envi¬ 
ronment developers make their TMS340-based systems TlGA-com- 
patible.The SDK, described below, is included as a subset to this kit. 

The SPK contains everything in the DDK plus all source code required 
to port the TIGA-340 interface to any TMS340 system, allowing all 
TIGA-compatible applications to run on that system. TMS340 source 
and 8086 object codes for a TIGA-compatible Windows/286 driver are 
also included. 

□ SDK: The Software Developer’s Kit (TI part number 
TMS340SDK-PC) 

The SDK is for those who want to develop direct TMS34010 code or 
custom, downloadable extensions to TIGA. In addition to the DDK, it in¬ 
cludes Tl’s TMS34010 C Compiler, Assembler, Bitmap Font, and Math/ 
Graphics source code libraries. 
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1.2 Features 

These are the key application-related features of the TIGA interface stan¬ 
dard; 

Applications run faster TIGA-340 provides the application writer with a 

dual-processor environment. This enables the 
tasks in the appiication to be run in parailei by 
partitioning them between the host and the 
TMS340 processors. The TIGA-340 interface is 
optimized to provide high-speed com¬ 
munications between the host and the TMS340 
family processors and to minimize the 
overhead in the processing of TIGA com¬ 
mands. 

Easy to use TIGA-340 provides applications with a base set 

of graphics primitives, with all the support 
required for the graphics subsystem. TIGA-340 
is compatible with the Microsoft C environment, 
and Microsoft deveiopment tools can be used 
for debugging the application. 

Extensible Where an application requires graphics 

functions that are not available in the TIGA base 
set of primitives, the application writer can 
develop user-extended primitives using 
TMS340 C, assembly language, or a mixture of 
the two. These user-extended primitives can be 
downloaded at runtime during the application 
initialization. 

Hardware independent Inquiry functions are provided that enable the 

application to determine the resolution, pixel 
size, etc., of the graphics subsystem and to 
adapt itself to the board on which it runs. 
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1.3 Architecture 

Figure 1-1 shows a blockdiagram of the TIGA-340 interface, illustrating the 
communication between the host routines and the TMS340 family proces¬ 
sor routines. 

As Figure 1-1 shows, the TIGA standard consists of four components: 

1) Application Interface (Al) 

2) Communication Driver (CD) 

3) Graphics Manager (GM) 

4) TIGA Extensions 
Figure 1-1. Block Diagram 



Host PC 


TMS340 Board 


The Application Interface (Al) is linked in with a TIGA Application. The Al 
consists of header files that reference TIGA function and type definitions, 
which may be used in the application, and of a library that the application 
links to when it is created. The Al does not actually contain the routines that 
interface to the TMS340 processor; these routines are contained in the com¬ 
munication driver. 

The Communication Driver (CD) is a Terminate-and-Stay-Resident (TSR) 
program that runs on a host PC. The CD is specific to the TMS340 board 
and is ported to it by a board manufacturer. A manufacturer ships the CD 
with the board; the CD is in afile called tigacd . exe . This file can be invoked 
by the user directly from the command line or placed in the autoexec . bat 
file to be executed at startup. The CD contains the functions used to commu¬ 
nicate between the host and the TMS340 board. These functions are in- 
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voked via calls in the Al made by the application. These communication 
functions take care of the host side hardware-dependent portion of TIGA, 
considering such things as whether the TMS340 board is memory-mapped 
or I/O-mapped. 

The Graphics Manager (GM) is a program that runs on the TMS340 board 
and is specific to the board that it resides on. It consists of a command ex¬ 
ecutive that handles the TMS340 side of the communications with the host, 
and a set of standard primitives that perform graphics operations. The GM 
typically resides in RAM on the board (although this is not a requirement) 
and therefore must be loaded onto the board after power-up. There are two 
mechanisms for doing this. TIGA comes with a linking loader tigalnk . exe, 
which loads the GM explicitly by invoking it with the -ix (Load and eXecute) 
flag. Alternately, the communication driver routines can sense whether the 
GM is running; when the application makes its first Al call, it detects if Al is 
not running and loads it. 

TIGA contains a set of primitives to perform a wide range of graphics opera- 
tions.The set of primitives can be extended by downloading the application 
functions onto the TMS340 system. These downloaded functions may be 
written using either the TMS340 C or assembiy languages. Downloading 
functions can decrease the host-TMS340 processor communications time 
and thus improve the performance of the application. 

The host application invokes most of the TIGA functions on the TMS340 
processor by downloading the parameters ofthefunction, along with a com¬ 
mand number, into one of severai communication buffers. The command 
number is an identifierforthe function to be executed. The command execu¬ 
tive, which forms part of the GM, determines which function is to be invoked 
and calls it with the parameters that have been passed to it. Because there 
are several buffers, the host downloads data into one buffer while the 
TMS340 is executing data from another. This parallelism produces signifi¬ 
cant speed improvement over the host performing the graphics manipuia- 
tion directly. 
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1.4 Extensibility 

Graphics standards before TIGA limited the software developer by provid¬ 
ing a fixed set of graphics drawing primitives. In the rapidly changing graph¬ 
ics market, afixed set of primitives is unacceptable. During the deveiopment 
of the TIGA graphics interface, incorporating extensibility into the standard 
was a major design goal. 

TIGA’s functionality can be extended by adding or manipulating its user ii- 
brary collection of C-callable routines. Figure 1-2 shows the configuration 
options for TIGA primitives. 


Figure 1-2. Primitive Configuration Options 


Base Set of TIGA 
Primitives 


TIGA Extended 
Primitives 

(example: patnfilLoval) 


Core Primitives (example: 
gsp__malloc) 




TIGA-compatible applications can be deveioped using the base set of primi¬ 
tives provided by the TIGA-340 Interface (as shown in the left hand side of 
Figure 1 -2). These TIGA primitives include the core primitives, which are al¬ 
ways available to the application, and the TIGA extended primitives, which 
are loaded if the application requires them.The set of graphics primitives 
and the performance of the TMS340 processor give many applications an 
acceptable level of graphics performance. However, an application has the 
ability to improve this performance by downloading user-extended primi¬ 
tives. The user-extended primitives can be downloaded to be used in addi- 
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tion to or instead of the TIGA extended primitives (as shown on the right- 
hand side of Figure 1-2). 

A hardware deveioper can implement the same concept of adding primi¬ 
tives. For example, if the developer of a TMS340-based graphics system 
incorporates hardware in addition to the TMS340 processor, access to this 
hardware can be provided through the TIGA interface. The access is ac¬ 
complished by developing a set of user-extended primitives which use the 
additional hardware functionality. Thus, the TIGA-340 interface provides a 
standard programming platform forthe software written by the hardware de¬ 
veloper using these user-extended primitives. 
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Getting Started 


This chapter contains instructions for installing TIGA on your system; 

Section Page 

2.1 System Requirements. 2-2 

2.2 Installing TIGA on your System. 2-4 

2.3 Modifying the Autoexec and the Environment. 2-9 

2.4 Running the TIGA Driver. 2-10 

2.5 The TIGA Environment Variable . 2-11 

2.6 TIGA Utility Programs . 2-12 

2.7 Required Non-TIGA Development Utility Programs . 2-17 

2.8 TIGA Syntax and Programming Examples . 2-18 
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2.1 System Requirements 

To ensure proper installation and operation of TIGA, your system must meet 
certain software and hardware minimum requirements. Consult the follow¬ 
ing sections for a list of these requirements, depending on the TIGA kit you 
are installing. 

2.1.1 TIGA Driver Developer’s Kit (DDK) System Requirements 

□ IBM PC, XT, AT or 100% compatible (hard disk required) 

□l 640KRAM 

□ LIM expanded memory plus expanded memory manager (for ADI driver 
only) 

Q Texas Instruments TMS34010 Software Development Board (SDB) 

□ MS-DOS or PC-DOS, version 2.13 or above 

□ Microsoft Macro Assembler, version 5.0 or above (if developing as¬ 
sembler-based applications/drivers) 

□ Microsoft C Compiler, version 5.0 or above (if developing C applica¬ 
tions) 

□ TMS34010 C Compiler and assembly-language tools, version 3.0 or 
above (if writing user-extended functions) 

r-1 

Note: 

The current version of TIGA supplied with the DDK is designed to run only 
on aTexas Instruments software development board (SDB). Pricing and or¬ 
dering information for the SDB is available from your local Texas Instru¬ 
ments Sales Office. 

I_I 


2.1.2 TIGA Software Porting Kit (SPK) System Requirements 

□ IBM PC,XT,AT or 100% compatible (hard disk required) 

□ 640KRAM 

□ LIM expanded memory plus expanded memory manager (for ADI driver 
only) 

□i Texas Instruments TMS34010 Software Development Board (SDB) 
(Only If you are not porting TIGA to a different board) 

□ MS-DOS or PC-DOS, version 2.13 or above 
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System Requirements 


□ Microsoft Macro Assembler, version 5.0 or above 

□l Microsoft C Compiler, version 5.0 or above (if developing C applica¬ 
tions) 

□ TMS34010 C Compiler and assembly-language tools, version 3.0 or 
above (if writing user extended functions and/or if porting TIGA to a dif¬ 
ferent board) 

I —.. ' " . . . ~i 

Note: 

The current version of TIGA supplied with the SPK is designed to run on 
a Texas Instruments software development board. However, all software 
necessary to port TIGA to a different TMS340 board is included in in the 
SPK. Consult Appendix D for information on how to port TIGA to a different 
TMS340 board. 

I_I 
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2.2 Installing TIGA on Your System 

I-1 

Note: 

If you have an earlier version of TIGA on your system, be aware that the 
TIGA installation procedure ovenwrites same-named files in the tiga and 
tigapgms directories. For this reason, files of previous versions of TIGA 
should be backed up, if needed, before proceeding with the new TIGA in¬ 
stallation. 


I_I 

Both the TIGA DDK and SPK kits have an automated installation program 
to aid in installing TIGA on your system. In general, the installation proce¬ 
dure for the DDK and the SPK are the same. 

The DDK package is a subset of the SPK; the SPK package contains all 
of the files in the DDK plus additional files required for porting purposes. 
Therefore, if you have both the DDK and the SPK packages, install only the 
SPK on your system. 

Follow these instructions to install your TIGA kit; 

Step 1 : Place disk #1 (DDK #1 or SPK #1) of your TIGA kit into drive A: 

Step 2: If A: is not your current drive, enter a : Q at the MS-DOS prompt. 

Step 3: Make sure you are at the root directory of A:. If you are not sure, 
enter cd\ Q at the MS-DOS prompt. 

Step 4: Enter setup dri ve : IQ where of/'/Ve/designates yourdestination 
drive (hard disk). For example, if you want to install TIGA on your 
C: hard disk, enter setup c: Q. 

Step 5: Follow the instructions displayed on the screen to complete instal¬ 
lation. 

During installation, you have the option of installing a collection of TIGA- 
compatible examples and demonstrations. It is recommended that these 
examples be installed because they are referenced as coding examples in 
this guide. 

The installation of your TIGA kit creates a number of subdirectories on your 
destination drive. Consult one of the following two sections (depending on 
the TIGA kit you installed) for information describing these subdirectories 
and the files contained within them. 
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2.2.1 Driver Developer’s Kit (DDK) Subdirectories 

Installing the DDK on your system creates the following subdirectories: 

Subdirectory Description 

\tiga TIGA root directory, TIGA drivers, system files, and 

utility programs 

\tiga\ai Application interface library 

\tiga\gm\extprims Extended primitives source code archive 
\tiga\inciude Include files 

\tigapgms TIGA compatible examples and demonstrations 

(see Section 2.2.3 for more information) 

The \tiga\gm\extprims directory Contains the self-extracting archive file 
extprims. exe. This archive contains source for every extended function 
available within TIGA. It enables you to choose the extended functions you 
need, link them with your specific user extensions, and create a custom 
TIGA dynamic load module with the TMS340 functions that your application 
or driver requires. To unarchive the source files contained in this archive, en¬ 
ter extprims from within this directory. 

2.2.2 Software Porting Kit (SPK) Subdirectories 

Installing the DDK on your system creates the following subdirectories: 

Subdirectory Description 

\tiga TIGA root directory, TIGA drivers, system 

files, and utility programs 

\tiga\ai Application interface library and source 

\tiga\cd TIGA communication driver source 

\tiga\gm TIGA graphics manager root directory 

\tiga\gm\corprims TIGA graphics manager core primitives 
\tiga\gin\extprims TIGA graphics manager extended primitives 
\tiga\gm\sdb TIGA graphics manager SDB specific files 
\tiga\inciude Include files 

\tigapgms TIGA Compatible examples and demonstrations 

(see Section 2.2.3 for more information) 
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2.2.3 TIGA Demonstrations and Example Subdirectories 

During installation, you have the option of installing a collection of TIGA 
compatible demonstrations and examples. When installed, the following di¬ 
rectories are created on the destination drive: 


\tigapgms 
\tigapgms\adi 
\tigapgms\asmtst 
\tigapgms\ball 
\tigapgms\clock 
\tigapgms\curve s 
\tigapgms\examp1es 
\tigapgms\flysim 
\tigapgms\stars 
\tigapgms\tests 
\tigapgms\tigademo 
\tigapgms\tigamode 
\tigapgms\tigalogo 
\tigapgms\windows 


TIGA compatible examples and demonstrations 

TIGA compatible AutoCAD example driver 

Assembly language application example 

Interrupt example using graphics 

Downloaded interrupt function example 

Floating-point example 

Examples supplied in Chapter 3 of this guide. 

3-D flying simulator example 

Downloaded function example 

TIGA test suite 

Demonstrates many of TIGA’s functions 
Board mode query/initialization program 
Demonstrates fixed-point math operations 
TIGA-compatible MS-Windows driver (SPK only) 


Each subdirectory contains a readme.ist file, complete source, and a 
make file to rebuild that particular demonstration. Consult the readme.1st 
file for a description of the demonstration and rebuilding instructions. 

If you opted not to load the TIGA examples during the initial TIGA kit installa¬ 
tion, you can install the examples and demonstrations at any time, following 
the installation instructions outlined on page 2-4. Simply insert program 
disk #1 into drive A: instead of the DDK or SPK disk #1 as directed in step 
1. Continue installation as described. 


2.2.4 Running a TIGA Demonstration 

After installing TIGA on your system, you can run any of the supplied dem¬ 
onstration programs. One such program, tigademo, is a free-running dem¬ 
onstration of TIGA’s graphics primitives. The following instructions outline 
how to run tigademo: 

1) At the MS-DOS prompt, enter 

set path=c:\tiga |^| 

This provides access to TIGA’s DOS commands from any directory. 

2) Enter 

set TIG]^-mc: \tiga |Q| 

This informs TIGA to look in the c:\tiga directory for TIGA-specific 
runtime files. 
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3) Enter 

cd \'tlgapgins\'txgademo |^| 

This directory contains the tigademo program. 

4) Enter 

tigacd 

This loads the TIGA communication driver (CD). The CD provides the 
communication interface between a TIGA application and the target 
TMS340-based board. Once loaded, the CD remains resident in 
memory and requires reloading only after rebooting your system. 

5) Finally, enter 

tigademo |Q| 

This executes tigademo. 

You can run any of the other supplied examples in a similar manner. 


I---1 

Note: 


Because the DDK/SPK is shipped with a Tl software development board 
(SDB) version of TIGA, you must have an SDB in your system (or have a 
version of TIGA compatible with your TMS340-board) before running any 
of the supplied examples. 
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2 . 2.5 TIGA Include Files 

The directory \tiga\ include contains include files used in the TIGA source 
code itself and when writing TIGA applications. These include files are di¬ 
vided in two groups: those designed to run on the host processor and those 
designed to run on the TMS340 processor. They are also divided, as to 
whether they are used in C-source files or in assembier source fiies as fol¬ 
lows: 

□ Host-side include files 

■ C-source 

extend . h Use When Calling TIGA extended primitives 

tiga .h Include always in a TIGA C program 

typedef s . h include when using TIGA structure types 

■ Assembler source 

extend. inc Use When Calling TIGA extended primitives, 
tiga. inc include always in a TIGA assembly program, 
typedef s. inc Include when using TIGA structure types 

□ TMS340-side include files 

■ C-source 

gspextnd . h Use for external declarations of all TIGA extended 

primitives 

gspgiobs . h Use for external declarations of all TIGA global 
variables 

gspregs . h Use for TMS340 register definitions 
gsptiga .h Use for external declarations of all TIGA core 
primitives 

gsptypes .h Include when using TIGA structure types 

■ Assembler source 

gspextnd. inc Use for external declarations of all TIGA extended 
primitives 

gspgiobs. inc Use for external declarations of ail TIGA global 
variables 

gspregs. inc Use for TMS340 register definitions 
gsptiga. inc Use for external declarations of all TIGA core 
primitives 

gsptypes. inc Include when using TIGA structure types 
gspmac. lib Use for macro library 
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2.3 Modifying Autoexec and the Environment 

After installing yourTIGAkit, you may want to make afew modifications and/ 
or additions to your autoexec. bat or comparable batch file. Note that these 
instructions use C: to identify the hard disk drive. Replace C; with the drive 
designator where you installed your particular TIGA kit: 

1) Append C:\tiga to the MS-DOS path: 

PATH=< existing PATH>;c;\tiga 

2) If you plan to develop TIGA-compatible applications in C or to rebuild 
any of the TIGA demos or the TIGA test suite, append 
c:\tiga\inciude to the Microsoft C compiler environment variable 

INCLUDE: 

set INCLUDE=<existing INCLUDE>;c:\tiga\inciude 

If you do not currently have an include environment variable in your 
autoexec.bat file, this command adds it. 

3) If you have the TMS340 C Compiler and assembly-language tools in¬ 
stalled on your system, then append c:\tiga\inciude to the A_DIR 
and C_DIR environment variables: 

set A_DIR=<existing A_DIR>;c;\tiga\iuciude 
set C_DIR=<existing C_DIR>; c;\tiga\iiicJude 

Again, if these environment variables currently do not exist, these com¬ 
mands add them. 

4) Add the following TIGA environment variable: 

set TIGA= -mc:\tiga 

See Section 2.5 on page 2-11 for a complete description of the TIGA 
environment variable. 

5) After modifying your autoexec.bat file, run it or reboot your PC. 
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2.4 Running the TIGA Driver 

To load TIGA: 

Enter tigacdB| at the MS-DOS prompt. The command syntax for tigacd 
is: 

tigacd [flag] 


Available options: 

Flag Description 

-i Reinstalls the TSR. This option forces a new copy of the TIGA com¬ 
munication driver (CD) to be loaded in memory, thereby superseding 
any previously installed CD. Note that reinstalling the TSR with the -i 
option forces reloading of the TIGA graphics manager. 

-u Uninstalls the TSR. This option causes the previousiy installed TIGA 
CD to be released from memory, disabling TIGA. To re-enable TIGA, 
enter: tigacd Q once again. 

-s Informs the TIGA CD to select operating modes valid for the SONY 
Multiscan monitor, rather than for the default monitor, the NEC Multi¬ 
sync monitor (SDB version only). 

After the TIGA CD is loaded, TIGA is ready to use; however, the TMS340 

side of TIGA has not yet been initialized. This is accomplished in one of the 

following ways: 

□ An application making a call to set_videomode(TIGA,INIT) checks 
whether the TIGA graphics manager (GM) is loaded and running on the 
TMS340 side. If so, both the host and TMS340 sides of TIGA are ready. 
If not, the GM is loaded, executed, and initialized prior to returning from 
the set_videomode function. 

Q Enter tigaink -lx from the MS-DOS command line after loading the 
TIGA CD, to force the TIGA GM to be loaded and executed. 

After loading the host and TMS340 sides of TIGA, your application is free 

to call TIGA’s core primitives. 
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2.5 The TIGA Environment Variable 

TIGA uses the environment variable tiga to get information about the loca¬ 
tion of TIGA system files, dynamic load modules, and the desired interrupt 
level. Set the TIGA environment variable using the following syntax: 


set TIGA = [flag] [string] [flag] [string] 


Currently, TIGA recognizes three flags: 

Flag Description 

-m Specifies the path for TIGA system files 

-1 Specifies the path for TIGA dynamic load user modules 

-i Specifies the host interrupt level used by the TIGA communication 

driver 

When TIGA is initially installed, all TIGA system files are placed in the TIGA 
directory of the destination drive. Specify this path using the -m flag of the 
TIGA environment variable. 

Any dynamic load modules loaded from a TIGA application must be located 
in either: 

□ the current directory from which the TIGA application is called or 

□ the path specified by the -i flag in the TIGA environment variable. 

By default, TIGA’s communication driver uses interrupt level 0x7F to com¬ 
municate with an application. Use the -i flag followed by the interrupt level 
(in hex format) in the TIGA environment variable to specify an alternate in¬ 
terrupt level. 

As an example, assume all TIGA system files are located in c : \tiga, user 
dynamic load modules are in d: \dim, and the desired interrupt level to use 
is 0x78. Set the corresponding TIGA environment variable: 

set T1GA= -me:\tiga -ld:\dlm -i0x78 [Ml 


2-11 





TIGA Utility Programs 


2.6 TIGA utility Programs 


The following TIGA utility programs are in TIGA’s root directory \tiga to 
simplify porting and/or applications development: 


TIGA Utility 

cc.exe 

cltiga.bat 
mg2tiga.exe 

tigamode.exe 


Description 

TMS340 tool shell program, used in make files 
that rebuild TIGA’s graphics manager 
Batch file to compile and link a TIGA application 
Utility to convert TMS340 math/graphics fonts to 
TIGA compatible fonts 

Utility to query available modes and select default 
mode 


2.6.1 cc Utility 

This utility is used primarily by the TIGA graphics manager make files during 
rebuilding. It is also useful in compiling TMS340 C or assembling assembly- 
language code. 

cc is executed from the MS-DOS command line. Enter cc with no parame¬ 
ters to display usage instructions. Additional information on how to use the 
cc utility can be found in the TMS34010 Software Developer’s Kit (SDK) 
User’s Guide. 

2.6.2 citiga Batch File 

The cltiga.bat batch file provides an easy way to compile and link a 
TIGA-compatible application (contained in a single C source file) to the 
TIGA application interface. It also supports symbolic debugging through Mi¬ 
crosoft’s CodeView ® debugger. The syntax for citiga is: 

citiga [-cd filename 


where -d is an option that specifies symbolic debug processing and file¬ 
name is the name of the C file to be processed. No extension should be spe¬ 
cified on the filename. 

I-1 

Note: 

The TIGA application interface library is independent of the Microsoft C 
model, thus, the citiga batch file does not specify any particular model and 
uses the default (small) model unless overridden. This can be done by set¬ 
ting the cl environment variable (consult the Microsoft C reference manual 
for details). 
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2.6.3 mg2ti9a Utility 

The mg2tiga Utility converts fonts compatible with the TMS340 Math/ 
Graphics function library to aformat compatible with the TIGA text functions. 
The command line syntax for ing2tiga. exe is 

mg2tiga MG font TIGA font [’’facename”] 


where: 
MG font 


is a binary or COFF object image of a Math/Graphics compat¬ 
ible font. 


TIGA font is the filename under which the converted font is saved. 

facename is an optional name of the font (up to 31 characters long) en¬ 
closed within double-quotes. If this parameter is not specified 
on the command line, mg 2 tiga prompts you for it. 

Here is an example of converting the Tl Roman 18-point font from the math/ 
graphics font library to TIGA format. 

1) Locate the library that containsTI Roman fonts. As supplied, this library 
is called t i_roman. lib and contains 12 fonts. A table of contents of 
this library: 

gspar -t ti roman IBI 


GSP 

Archiver 

Version 

3.00 




(c) 

Copyright 

1985, 1988, 

Texas Instruments Incorpo 

FILE NAME 

SIZE 


DATE 




ti 

romll.obj 

2358 

Thu 

Jun 

12 

12:00:32 

1986 

ti 

roml4.obj 

2744 

Thu 

Jun 

12 

12:02:20 

1986 

ti 

roml6.obj 

3130 

Thu 

Jun 

12 

12:04:12 

1986 

ti 

roml8.obj 

3258 

Thu 

Jun 

12 

12:06:06 

1986 

ti 

rom20.obj 

3898 

Thu 

Jun 

12 

12:08:06 

1986 

ti 

rom22.obj 

4538 

Thu 

Jun 

12 

12:10:16 

1986 

ti 

rom26.obj 

5432 

Thu 

Jun 

12 

12:12:34 

1986 

ti 

romSO.obj 

6330 

Thu 

Jun 

12 

12:15:00 

1986 

ti_ 

_roin33. ob j 

7098 

Thu 

Jun 

12 

12:17:36 

1986 

ti_ 

_rom38. ob j 

9658 

Thu 

Jun 

12 

12:20:42 

1986 

ti 

_rom52.obj 

16698 

Thu 

Jun 

12 

12:25:00 

1986 

ti 

_rom78.obj 

34878 

Wed 

Jun 

18 

02:45:56 

1986 


2) Extract the desired font, in this case ti_romi8. ob j. 
Examplei gspar X 'ti_roman 'ki_roml8 .ob j |^| 

3) Now use mg 2 tiga to conveit it to TIGA format. 
Example: Ing2'biga 'ki_roinl8. ob j romanl8.£n't IE 
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At this point, mg2tiga prompts you to enter a facename for the font. 
Thisfacename can be up to 31 characters iong and shouid be the name 
of the font. 

Example: MGFL to TIGA font converter 

[ Converting: ti_roml8.obj -> romanlS.fnt ] 
Enter facename (31 chars max): TI ROMAN 

After you have entered the facename, mgatiga dispiaysthe MG font header 
and then the new TiGA font header. A prompt to press Q foiiows each of 
these dispiays. After entering this information, the conversion is compiete. 
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[-Old Font Header-] 

fonttype: 9000 
firstchar: 0000 
lastchar: OOff 
widemax: 0010 
kernmax: 0000 
ndescent: fffd 
charhigh: 0011 
owtloc: 046a 
ascent: OOOe 
descent; 0003 
leading: 0002 
rowwords; 0033 
[ Press return ]-> 

[-New Font Header-] 

magic: 8040 
length: 00000b 
facename: TI ROMAN 
first: 0000 
last: OOff 
maxwide: 0010 
maxkern: 0000 
charwide: 0000 
avgwide: 0008 
charhigh; 0011 
ascent: OOOe 
descent; 0003 
leading: 0002 
rowpitch: 00000330 
oPatnTbl: 00000250 

oLocTbl: 00003880 

oOwTbl: 000048a0 
[ Press return ]--> 
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2.6.4 tigamode Utility 

The tigamode Utility allows you to interrogate the operating modes of the 
TiGA-compatible graphics board in your system. It also enables you to se¬ 
lect a default mode for your board. For additional information and complete 
source for the tigamode utility, consult the \tigapgms\tigamode directory. 
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2.7 Non-TIGA Development Utility Programs 

TIGA development and/or porting relies heavily on the use of the Microsoft’s 
Macro Assembler and/or Microsoft’s C compiler packages. Specifically, 
both packages must be version 5.0 or later to ensure compatibility with 
TIGA. 

TIGA contains batch files that aid in rebuilding the TIGA communications 
driver and graphics manager (if you have the SPK), and batch files to com¬ 
pile and link your applications with the TIGA applications interface. These 
batch files use the following utility programs, which are bundled with the indi¬ 
cated Microsoft programming package: 

Utility program Description 

cl.exe Microsoft C compiler shell program 

lib. exe MS-DOS library manager, supplied with DOS 

link. exe MS-DOS linker, supplied with both packages 

make. exe Make Utility, Supplied with both packages 

These programs must be accessible from TIGA’s batch files (via the PATH 
environment variable) to ensure proper operation. 
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2.8 TIGA Syntax and Programming Examples 

The definition of the TIGA syntax and the coding examples supplied in this 
guide are written primarily in Microsoft C, since Microsoft C is commonly 
used to write DOS applications. The high-level language syntax in C is simi¬ 
lar to that of many other high-level languages and even programmers unfa¬ 
miliar with C will understand the syntax. TIGA, however is not restricted to 
Microsoft C, although this initial release does rely on the Microsoft C calling 
conventions. Future versions of TIGA may be developed for other C compil¬ 
ers and other languages. 

The current version of TIGA also provides a simple interface for Microsoft 
assembly language programmers. The three TIGA include files (tiga.h, 
extend, h, and typedefs .h) all have assembly language equivalents that 
use macros to provide a simple interface to call TIGA functions. An example 
of how to call TIGA functions from the assembler is provided in the 
\tigapgins\asnitst directory. Consult the readme. 1st file in that directory 
for more details on the use of macros. Also provided in the inciude files are 
macros used to simplify the definition of user extensions. These macros, 
which mirror their C counterparts, are described in Chapter 4 of this user’s 
guide. 
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TIGA Application Interface 


The following sections list the TIGA primitives, first in their functional 
groups, and then alphabetically, with a description and example of their use. 
Appendix B provides further information concerning the drawing functions. 

This chapter describes the TIGA application interface, inciuding the foilow- 
ing topics: 


Section Page 

3.1 Base Set of TIGA Primitives.3-2 

3.2 Summary Table of Functions by Functional Group.3-3 

3.3 Alphabetical List of Functions ..3-13 
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3.1 Base Set of TIGA Primitives 

From an application programmer’s point of view, TIGA (Texas Instruments 
Graphics Architecture) consists of a set of functions which the application 
can invoke to perform graphics-related operations. These functions may run 
entirely on the host PC, on the TMS340 board, or on both. They fall into two 
classes, core and extended: 

□ Core Primitives 

The core primitives, such as set_palet, are always available during a 
TIGA session. 

□ Extended Primitives 

The extended primitives, such as fiii_rect, consist primarily of drawing 
functions. They are extended because the application has to load them 
when initializing TIGA. If the application requires installation of its own 
drawing functions, with parameters different from those used in TIGA, 
the extended primitives can be excluded at initialization time. Excluding 
the extended primitives frees up memory on the TMS340 board for user 
extensions. 
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3.2 Summary Table of Functions by Functional Group 
3.2.1 Graphics System Initialization Functions 


Function 

Description 

Type 

cdjs_alive 

Return if TIGACD is running 

Core 

functionjmplemented 

Return if a function is implemented 

Core 

get_config 

Return board configuration 

Core 

get_modeinfo 

Return board configuration 

Core 

get_videomode 

Return current emulation mode 

Core 

gsp_execute 

Execute a COFF program 

Core 

install_primitives 

Install extended primitives 

Core 

install_usererror 

Install user error handler 

Core 

loadcoff 

Load a COFF program 

Core 

set_config 

Set graphics configuration 

Core 

setjimeout 

Set timeout timing value 

Core 

set_videomode 

Set emulation mode 

Core 

synchronize 

Make host w'ait for GSP to idle 

Core 


The graphics system initialization functions deal with the initialization of the 
TIGA environment. Every application mustcaIlset_videomodewithaTiGA 
argument prior to invoking any other TIGA function. There are different 
styles of Initialization that can be performed and they are detailed In the de¬ 
scription of set_^videomode. Similarly, on exit, every TIGA function must 
call set_videomode with a mode of previous or some other IBM emulation 
mode, if the TMS340 board also serves as the primary graphics adapter, 
set_videomode switches the TMS340 board back into emulation mode 
prior to returning to DOS. 

To use the TIGA extended primitives, the application must first call the 
install_primitives function. This call needs to be done only once, if the dy¬ 
namic heap pool on the TMS340 board has not been reinitialized. 

The get_config function returns the current board configuration (resolution, 
pixel size etc) to the application. Typically a board can be configured in more 
than one mode and the get_modeinfo, set_config functions are provided 
to inquire and select alternate modes. Typically an application uses whatev¬ 
er mode the board is set up in (via get_config). The end user can swap be¬ 
tween different modes with the TIGAMODE utility (described in Chapter 2). 
That utility makes calls to the get_modeinfo and set_config functions. 

TIGA consists of two distinct parts: a host part (the communication driver), 
which takes data from the application and sends it to one of the communica¬ 
tion buffers accessible to the TMS340, and a TMS340 part (the graphics 
manager), which takes the data from the host and performs the graphics op- 


3-3 



Summary Table of Functions by Functional Group 


eration. The processors in these two portions work asynchronousiy. Some¬ 
times the host portion hastowaitfortheTMS340 portion; for example: when 
the TMS340 returns data to the host or when the host waits for a free com¬ 
munication buffer to use. The time the host has to wait for the TMS340 de¬ 
pends on what the TMS340 is doing for the application. 

TIGA has a built-in default time of 5 seconds, after which it displays an error 
message on the screen to inform the application that there was no communi¬ 
cation with the TMS340. This allows the user to break out if there is an error, 
or to continue waiting. If this default time is not acceptable it can be changed 
using the set_timeout function. The application can trap error calls by in¬ 
stalling its own error handler function using instalLusererror . There is an 
example of this after the description of InstalLusererror. 

Sometimes it is desirable to force the host to wait for the TMS340 to com¬ 
plete an operation before proceeding. Consider the case where the 
TMS340 is performing a bItbIt of data into memory and the host is then to 
upload the data using gsp2hostxy. Because the host and TMS340 work 
asynchronously, it is possible for the gsp2hostxy function to start copying 
data before the bItbIt has completed. This can be solved by the application 
calling the synchronize function, which causes the host to wait until all 
TMS340 functions are completed, prior to the call to upload the data. 

3.2.2 Clear Functions 


Function _ Description _ Type 

clear_frame_buffer Clear entire frame buffer Core 

clear_page Clear current drawing page Core 

clear_screen Clear screen Core 


The clear functions provide different ways to dearths screen. They all at¬ 
tempt to utilize any special memory functions (such as shift-register trans¬ 
fers) that the board or the memory chips themselves may have to perform 
the clear function as quickly as possible. The clear_frame_buffer clears 
the entire frame buffer, which may consist of multiple display pages and 
areas of offscreen (non-displayable) memory. 

The clear_screen function clears only the visible portion of the screen. For 
configurations that contain multiple display pages, only the current drawing 
page is cleared. The clear_page function is similar to the clear_screen 
function except that it does not ensure that data in offscreen memory is kept 
intact. This is because, depending on how the frame buffer is designed, it 
may be possible to clear a page using shift-register transfers; however, cer¬ 
tain offscreen memory areas may also be affected. Thus, to keep offscreen 
memory integrity, an application should use the clear_screen function. If 
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offscreen memory integrity is not a concern, the clear_page function may 
be the fastest option on certain boards. 

3.2.3 Graphics Attribute Control Functions 


Function 

Description 

Type 

cpw 

Compare point to window 

Core 

get_colors 

Return foreground/background colors 

Core 

get_env 

Return current environment structure 

Core 

getjDmask 

Return color plane mask 

Core 

get_ppop 

Return pixel processing operation 

Core 

get_transp 

Return transparency mode 

Core 

get_windowing 

Return windowing mode 

Core 

set_bcoior 

Set background coior 

Core 

set_clip_rect 

Set ciipping rectangle 

Core 

set_colors 

Set foreground and background colors 

Core 

set_draw_origin 

Set drawing origin 

Ext 

set_fcolor 

Set foreground coior 

Core 

set_patn 

Set current pattern description 

Ext 

setjDensize 

Set current pensize 

Ext 

set_pmask 

Set color plane mask 

Core 

set_ppop 

Set pixel processing operation 

Core 

set_transp 

Set transparency mode 

Core 

set_windowing 

Set windowing mode 

Core 

transp_off 

Disable pixel transparency 

Core 

transp_on 

Enable pixel transparency 

Core 


The graphics output functions use impiied operations cailed the graphics at¬ 
tributes to perform the drawing operations described below. These attrib¬ 
utes are initialized and can be queried using the functions in this group. The 
graphics attributes consist of 

Foreground Color Primary drawing color of all primitives. The color val¬ 
ue is an index running from 0 to two-to-the-pow- 
er-of-the-current-pixel-size. The value will typically 
be an index into the current palette (see next section). 

Background Color Secondary drawing coior, used in patterns, text and 
bitblt functions. 

Plane Mask Enables the bits in a pixel to represent different 

planes. 

Pixel Processing Determines the operation performed on source and 
destination pixeis in any pixel operation. 

Transparency Determines whether a pixel write should be inhibited 
if the pixei coior is transparent. 
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Windowing 


Drawing Origin 


Fiii Pattern 


Drawing Pen 


Allows regions of the screen to be clipped to ensure 
no drawing occurs outside the designated window. 

By default the drawing origin is the top-left hand cor¬ 
ner of the screen, but this can be moved anywhere. 

Used by all the patn drawing functions that fill a re¬ 
gion with a pattern instead of a solid color. 

Used by all the pen drawing functions to outline a re¬ 
gion with a pen of the specified width and height, rath¬ 
er than with a single- pixel wide line. 


For further details concerning the drawing functions, see Appendix B. 


3.2.4 Palette Functions 


Function 

Description 

Type 

get_nearest_color 

Return nearest color in a palette 

Core 

get_palet 

Return an entire palette 

Core 

get_palet_entry 

Return a palette entry 

Core 

lnit_palet 

Initialize default palette 

Core 

set_palet 

Set an entire palette 

Core 

set_palet_entry 

Set a palette entry 

Core 


The palette functions are graphics attributes and deserve special attention 
because they may vary from board to board. Ideally, the application should 
be able to set the palette to any particular desired value, but if the palette 
is in ROM, this is not possible. Use functionjmplemented to determine 
if the palette entries can be set. If they cannot be set, use the get_near- 
est_color function to find the best entry to the desired color stored in ROM. 
Also, different palettes allow different bits-per-gun. Determine the bits-per- 
gun using the paiet_gun_depth field in the CONFIG structure or the 
getjjalet function. The get_palet and get_palet_entry functions return 
the physical colors stored in the palette. Thus, if a palette entry is set with 
8 bits of red to hexadecimal FF on a particular board (such as the Tl SDB), 
where only 4 bits per gun are used, invoking get_palet_entry for that entry 
would return a red value of FO to indicate that the LS 4 bits were ignored. 
An example describing this is shown after the description of 
get_palet_entry. 

If possible, the palette is initialized to a default set of commonly-used colors 
(defined in the tiga.h insert file) by a call to init_palet. 
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3.2.5 Graphics Output Functions 


Function 

Description 

Type 

drawjine 

Draw line 

Ext 

draw_oval 

Draw ellipse outline 

Ext 

draw_ovalarc 

Draw ellipse arc 

Ext 

draw_piearc 

Draw ellipse pie slice 

Ext 

draw_point 

Draw single pixel 

Ext 

draw_polyline 

Draw list of lines 

Ext 

draw_rect 

Draw rectangle outline 

Ext 

fill_convex 

Draw solid convex polygon 

Ext 

fill_ova! 

Draw solid ellipse 

Ext 

filLpiearc 

Draw solid ellipse pie slice 

Ext 

filLpolygon 

Draw soiid polygon 

Ext 

fill_rect 

Draw solid rectangle 

Ext 

frame_oval 

Draw oval border 

Ext 

frame_rect 

Draw rectangular border 

Ext 

patnfiil_convex 

Draw patterned convex polygon 

Ext 

patnfill_oval 

Draw patterned ellipse 

Ext 

patnfill_piearc 

Draw patterned pie siice 

Ext 

patnfilljjolygon 

Draw patterned polygon 

Ext 

patnfill_rect 

Draw patterned rectangle 

Ext 

patnframe_oval 

Draw patterned oval border 

Ext 

patnframe_rect 

Draw patterned rectangular border 

Ext 

patnpenjine 

Draw line with pattern and pen 

Ext 

patnpen_ovalarc 

Draw oval arc with pattern and pen 

Ext 

patnpenjDiearc 

Draw pie slice with pattern and pen 

Ext 

patnpen_point 

Draw pixel with pattern and pen 

Ext 

patnpenjDolyline 

Draw lines with pattern and pen 

Ext 

penjine 

Draw line with pen 

Ext 

pen_ovalarc 

Draw an oval arc with pen 

Ext 

pen_piearc 

Draw pie slice with pen 

Ext 

pen_point 

Draw point with pen 

Ext 

penjDolyline 

Draw lines with pen 

Ext 

seedjill 

Fill region with color 

Ext 

seed_patnfill 

Fill region with pattern 

Ext 

styledjine 

Draw styled line 

Ext 


The graphics output functions are self-explanatory. Specific examples on 
how to use fill patterns are shown in patnfill_piearc and for drawing pens 
in patnpenjine. These examples also explain other patn and pen func¬ 
tions. Additional examples of drawing functions are given for drawjine, 
draw_oval, draw_ovalarc, draw_point, draw_polyline, fill_polygon, 
and styledjine. 

For further details concerning the drawing functions, see Appendix B. 
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3.2.6 Poly Drawing Functions 


Function 

Description 

Type 

drawjDolyline 

Draw polyline 

Ext 

fill_convex 

Fill convex polygon 

Ext 

filLpolygon 

Fill polygon 

Ext 

patnfill_convex 

Pattern fill convex polygon 

Ext 

patnfill_polygon 

Pattern fill polygon 

Ext 

patnpenjDolyline 

Pattern pen polyline 

Ext 

penj 3 olyline 

Pen polyline 

Ext 


The TIGA communication driver functions pass the arguments of aii the 
TiGA primitives into a communication buffer for the TiGA graphics manager 
to use. Nearly aii TIGA primitives have fixed size arguments that fit easily 
into the communication buffer. This is not the case with the poly drawing 
functions, which have a point list parameter that can be of any length. It is 
easy for the function to overflow the buffer, destroying the TIGA environ¬ 
ment. The application can either check the size of the data that it is sending, 
against the communication buffersize in the CONFIG structure, oritcan use 
alternate entry points (with an _a appended to the function name), that use 
a buffer, allocated from the dynamic heap pool, to store the data. However, 
these alternate entry points are slower. 

3.2.7 Workspace Functions 


Function 

Description 

Type 

filLpolygon 

Fill polygon 

Ext 

get_wksp 

Return offscreen workspace 

Core 

patnfilLpolygon 

Pattern fill polygon 

Ext 

set_wksp 

Set a temporary workspace 

Core 


The polygon fill functions use an implied operand of atemporary workspace. 
This workspace is a 1 bit-per-pixel representation of the display screen and 
may be allocated from offscreen-memory in the TIGA port for the board be¬ 
ing used. This can be determined by the get_wksp function. If the area can¬ 
not be allocated from offscreen-memory, then it must be allocated from heap 
and assigned using the set_wksp function. An example showing how to do 
this follows the fill_polygon description. 

3.2.8 Pixel Array Functions 


Function 

Description 

Type 

bitbIt 

BitbIt source array to destination 

Ext 

set_dstbm 

Set destination bitmap 

Ext 

set_srcbm 

Set source bitmap 

Ext 

swap_bm 

Swap source and destination bitmaps 

Ext 

zoom_rect 

Zoom source rectangle 

Ext 
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The bitbIt function transfers a rectangular array of pixels in TMS340 
memory. The function uses two implied operands (source bitmap and desti¬ 
nation bitmap) which are set, by default, to the screen. When they are set 
to a linear address, the bItbIt function can then save data offscreen and re¬ 
store it again (see example following set_dstbm). The bitbIt function can 
also be used to expand a linear bitmap which is at 1 bit-per-pixel to a color 
bitmap (see example following zoom_rect). 

The destination bitmap is an implied operand for all drawing functions. If it 
is set to anything other than the screen, all drawing primitives (other than 
bitbIt) abort. In the future, linear drawing capability may be added to each 
of the drawing functions so they can draw into a linear bitmap. 

The source bitmap is ignored by all functions except bitbIt and zoom_rect. 
The latter is used to scale a source pixel array into any size destination array. 
See the example following the function description. 


3.2.9 Text Functions 


Function 

Description 

Type 

delete_font 

Remove a font from the font table 

Ext 

get_fontinfo 

Return font physical information 

Core 

getjextattr 

Return text rendering attributes 

Ext 

init_text 

Initialize text drawing environment 

Core 

installjont 

Install font into font table 

Ext 

selectjont 

Select an installed font for use 

Ext 

setjextattr 

Set text rendering attributes 

Ext 

text_out 

Render an ASCII string 

Core 

text_width 

Return the width of an ASCII string 

Ext 


The text functions are partly core and partly extended primitives. In the core 
is a system font and the text_out primitive along with get_fontlnfo (which 
returns font size information) and init_text (to reset the text environment). 
The extended primitives lnstall_font, select_font, and delete_font allow 
the addition of TIGA fonts. There are over 100 TIGA fonts available, which 
the application loads from disk on the host side (or links-in with the host 
application) and downloads onto the TMS340 side. An example illustrating 
this is in install_font. The set/get_textattr function allows the text attrib¬ 
utes such as inter-character spacing, to be adjusted by the application. 

For more details on the font structure, see Appendix A. 


3-9 



Summary Table of Functions by Functional Group 


3.2.10 Cursor Functions 


Function 

Description 

Type 

get_curs_state 

Return cursor current state 

Core 

get_curs_xy 

Return cursor position 

Core 

set_curs_shape 

Set cursor shape 

Core 

set_curs_state 

Make cursor visible/invisible 

Core 

set_curs_xy 

Set current cursor position 

Core 


The cursor functions support the graphics cursor routine. The cursor can be 
enabied or disabled via the set_curs_state function and its position can be 
modified using set_curs_xy. The set_curs_shape enables an arbitrary 
shaped cursor to be used. An example showing how the cursor may be driv¬ 
en by the host mouse follows the description of set_curs_shape. 

3.2.11 Graphics Utiiity Functions 


Function 

Description 

Type 

getjjixel 

Read contents of a pixel 

Ext 

Imo 

Return left-most-one bit number 

Core 

page_busy 

Return status of page flipping 

Core 

pagejiip 

Set display and drawing pages 

Core 

peek_breg 

Read from a B-file register 

Core 

poke_breg 

Write to a B-file register 

Core 

rmo 

Return right-most-one bit number 

Core 

wait_scan 

Wait for a designated scan-line 

Core 


The graphics utility functions are a group of miscellaneous graphics-related 
functions, most of which require no explanation other than what is given with 
the individual functions. 


The wait_scan and page_flip/busy functions are mechanisms to aid ani¬ 
mated sequences. wait_scan waits for a particular scan line, enabling data 
to be drawn on one part of the screen while a different part is being dis¬ 
played. This feature provides a flicker-free display but is limited in the 
amount that it can draw before the display moves to the area that is being 
drawn into. The use of multiple drawing pages is a much more effective way 
where one page can be drawn while another is being displayed. This is the 
only way to ensure a flicker-free display. However, it does require at least 
double the amount of memory for the frame buffer. 

The CONFIG structure supplies the number of display pages. If the number 
of pages is greater than 1, use the page_fiip function to select a page for 
drawing and a page for displaying. The flip of the pages is synchronized with 
the start of VBLNK for the best visual effect. The page_busy function must 
be polled prior to drawing into the new page. 
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3.2.12 Pointer-Based Memory Management Functions 


Function _ Description _ Type 

get_offscreen_memory Return offscreen memory blocks Core 

gsp2gsp Copy from GSP memory to GSP memory Core 

gsp_calloc Allocate and clear GSP memory Core 

gspjree Deallocate GSP memory Core 

gsp_malloc Allocate GSP memory Core 

gsp_maxheap Return largest free block Core 

gsp_minit Reinitialize GSP memory heap pooi Core 

gsp_realloc Resize aiiocated block of memory Core 


The heap management functions (gsp_malloc, gsp_free, gsp_calloc, 
gsp_realioc) are familiar to C application programmers. Identicai heap 
management for host memory is provided in Microsoft C runtime support. 
The gsp_minit function initializes the heap pool (freeing aii aiiocated point¬ 
ers). Because the program memory is shared between stack and heap, this 
function can also be used to adjust the memory used for stack (and thus, 
leaving the remainder memory for heap). The gsp_niaxheap function re¬ 
turns the largest contiguous biock of heap available (which is also the total 
heap size at the start of an application) and can determine how much data 
can be ioaded from the host to the TMS340. 

The gsp2gsp function provides a memory copy function (as opposed to 
bitbit, which is a pixel array copy). It handles overlapping memory areas. 

The get_offscreen_memoty function returns data concerning the size and 
addresses of avaiiable offscreen memory, which are separate from the heap 
pooi. Ailocation of these areas is performed by the appiication. The off¬ 
screen memory may be used for the temporary workspace (see Section 
3.2.7). 

3.2.13 Communication Functions 


Function 

Description 

Type 

cop2gsp 

Copy coprocessor to GSP memory 

Core 

fieid_extract 

Extract data from GSP memory 

Core 

fieidjnsert 

Insert data into GSP memory 

Core 

get_vector 

Get address at a TMS340 trap vector 

Core 

gsp2cop 

Copy GSP memory to coprocessor 

Core 

gsp2host 

Copy from GSP into host memory 

Core 

gsp2hostxy 

Copy rectangular area from GSP to host 

Core 

host2gsp 

Copy from host into GSP memory 

Core 

host2gspxy 

Copy rectangular area from host to GSP 

Core 

set_vector 

Set contents of GSP trap vector 

Core 
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The communication functions transfer data between host and TMS340 
memory spaces, or between TMS340 and its coprocessor. 

3.2.14 Extensibility Functions 

Function _ Description _ Type 

create_aim Create absoiute ioad moduie Core 

create_esym Create external symbol table file Core 

flush_esym Flush external symbol table file Core 

flush_extended Flush all user extensions Core 

get_isr_priorities Return interrupt service routine priorities Core 

instalLalm Install absolute load module Core 

instalLprimitives Install extended drawing primitives Core 

install_rlm Install relocatable load module Core 

setjnterrupt Set an interrupt handler Core 

The extensibility functions are all concerned with extensibility. Their use is 
described in detail in Chapter 4. 
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3.3 Alphabetical List of Functions 

This section contains a reference for TIGA functions in alphabetical order. 
Each discussion 

□ Shows the syntax of the function declaration and the arguments that the 
function uses. 

□ Contains a description of the function operation, which explains input 
arguments and return values. 

□ Provides an example of the use of some functions. 
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bitbIt BitBIt in GSP Memory 


Syntax void bitblt(width, height, srcx, srcy, dstx, dsty) 

short width; 
short height; 
short srcx; 
short srcy; 
short dstx; 
short dsty; 

Type Extended 

Description The bitblt function copies data from the TMS340’s source bitmap, which is 
installed by the set_srcbm function into the destination bitmap. The desti¬ 
nation bitmap is in turn installed bytheset_dstbm function. The bitmap data 
is a rectangular area whose top left-hand corner is at coordinates 
(srcx, srcy) in the source bitmap of size width by height, into the destina¬ 
tion bitmap, starting at coordinates (dstx, dsty). The pixel size of the two 
bitmaps should either be equal or, if they are not, one of the pixels sizes must 
be equal to 1. 

If the pixel sizes are equal, then the rectangular area is copied. If both source 
and destination bitmaps are set to the screen, then a check is made to see 
if the areas overlap. If they do, the bitblt direction is set to avoid destroying 
the source bitmap before it is copied. 

If the source bitmap pixel size is 1, the bitmap is expanded to color in the 
destination array. 1s in the source bitmap are drawn in the current fore¬ 
ground color and Os are drawn in the current background color. 

If the destination bitmap pixel size is equal to 1, then a contract function is 
performed. Pixels in the source array that are equal to the current back¬ 
ground color are set to 0 in the destination array. All other colors are set to 
1 . 

When the destination bitmap is set to the screen, the function attempts to 
clip the destination bitmap to the current clipping rectangle set by the 
set_clip_rect function. This only occurs it the pitch of the source and desti¬ 
nation pitch are a power of two (greater than or equal to 16). The source 
pitch is set by the user in the set_srcbm function. If the destination bitmap 
is the screen, its pitch is defined in the disp_pitch field of the CONFIG 
structure (see Appendix A). If the pitches are not a power of two, you must 
pre-clip the destination bitmap. 
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Example linclude <tYpedefs.h> 

#include <tiga.h> 

#include <extend.h> 

CONFIG config; 

main () 

{ 

if (set_videomode(TIGA, INIT | CLR_SCREEN)) 

{ 

if (install_primitives() >= 0) 

{ 

get_config(&config); 
set fcolor(BLUE); 


/* fill the top left quarter of the screen '^/ 

/* with a blue rectangle '^/ 

fill_rect (config.mode.disp_hres»l, 

config.mode.disp_vres»l, 0, 0)/ 

/* copy one quarter of the rectangle with top */ 

/* left-hand corner at the center of the screen 


bitbIt (config.mode.disp_hres»2, 

config.mode.disp_vres»2, 0, 0, 
config. mode. disp_hres»l, 
config.mode.disp_vres>>l); 

} 

set_videomode(PREVIOUS, INIT); 

} 

} 
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CCl_is_alive Return If TIGACD is Running 

Syntax int cd_is_alive o 

Type Core 

Description The cdjs_allve returns true (nonzero) if the communication driver (CD) 
has been installed, or false (zero), otherwise. This function is an alternate 
entry point to set_videomode for applications that require only the host- 
side entry points of TIGA without loading the graphics manager. If this 
function returns true (nonzero), then the following host-only primitives may 
be used: 

□ field_extract 

□ fieldjnsert 

□ gsp2host 

□ gsp2hostxy 

□ gsp_execute 

□ host2gsp 

□ host2gspxy 
□i loadcoff 

Before a call to any other TIGA function, a call must first be made to 
set_videomode with a tiga parameter. 
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Syntax void clear_frame_buffer (color) 

long color; 

Type Core 

Description The ciear_frame_buffer function performs a rapid clearing of the entire 
display memory, by setting it to the color index specified. If the color is set 
to -1 the current background color is used. If the configuration is such that 
the screen can be cleared using shift-register transfers, this is done, 
providing a very rapid clearing. If the configuration contains multiple display 
pages all pages are cleared. The integrity of offscreen data cannot be 
guaranteed using this function. If this is of concern to the calling program, 
then the clear_screen function should be used. 

If the graphics display board uses display memory to store palette informa¬ 
tion (as in the TMS34070), this area should be left intact by this function. 


3-17 



Clear__page Clear Current Drawing Page 


Syntax 

Type 

Description 


void clear_page(color) 
long color; 

Core 

The ciear_page function performs a rapid clearing of the current drawing 
page by setting it to the color index specified. If the color is set to -1 the cur¬ 
rent background color is used. It provides very rapid clearing if the 
configuration allows the use of shift-register transfers. If the configuration 
contains multiple display pages, only the current drawing page is cleared. 
However, the integrity of offscreen data cannot be guaranteed using this 
function. If this is of concern to the calling program, then the clear_screen 
function should be used. 

If the graphics display board uses display memory to store palette informa¬ 
tion (as in the TMS34070), this area should be left intact by this function. 
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Clear Screen Clear screen 


Syntax 

Type 

Description 


Exampie 


void clear_screen(color) 
long color; 

Core 

The clear_screen function performs a rapid clearing of only the visible 
portion of the display memory, by setting it to the color specified index. If the 
color is set to -1, the current background color is used. It provides very rapid 
clearing if the configuration allows the use of shift-register transfers. 
However, this function clears only the current drawing page (in a multiple 
paged frame buffer) and does not affect any offscreen memory. If the 
offscreen memory data does not have to be conserved, then a more rapid 
fill may be possible using the clear_page function. 

If the graphics display board uses display memory to store palette informa¬ 
tion (as in the TMS34070), this area should be left intact by this function. 

See functionjmplemented. 
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C0p2gsp Copy from Coprocessor Memory to GSP Memory 


Syntax 


Type 

Description 


void cop2gsp(copid, copaddr, gspaddr, length) 
short copid; 
long copaddr; 
long gspaddr; 
long length; 

Core 

The cop2gsp function copies data from the address space of the coproces¬ 
sor with ID copid (a number from 0 —7, with 4 being broadcast, as defined 
in the TMS34020 specification) into TMS340 memory. The data to be trans¬ 
ferred is in 32-bit long words. 
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Syntax short cpw(x, y) 

short X, y; /* pixel coordinates */ 

Type Core 

Description The cpw function generates 4-bit outcode based on a pixel’s position rela¬ 
tive to the current clipping window. Arguments x and y are the coordinates 
of the pixel. 

The outcode value is contained in the 4 LSBs of the return value. Outcode 
values include 

OOOO 2 if the point lies within the window. 

01XX 2 if the point lies above the window. 

1 0 XX 2 if the point lies below the window. 

xxOI 2 if the point lies left of the window. 

xxl O 2 if the point lies right of the window. 

Refer to the TMS34010 User’s Guide for a detailed description of the out- 
codes. 
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creat©_alm Create Absolute Load Module 

Syntax int create_alm(rlm_naine, alin_name) 

char far *rlm._name; 
char far *alm_name; 

Type Core 

Description The create_altn function converts the relocatable load module (specified 
by rlin_name ) into an absolute load module and saves it under the filename 
specified by aim_name. If no file extension is supplied for the RLM, then an 
extension of. rlm is used. If no extension is supplied for the ALM, then an 
extension of .alm is used. If no path information is specified, this function 
looks first in the current directory and then in the directory specified by the 
TIGA environment variable. 

If the ALM file already exists, the procedure does nothing, this saves time 
by creating the ALM file only once. If a new ALM file is desired, the old one 
must be deleted explicitly. For more details on extensibility and an example 
of the use of this function refer to Chapter 4. 

If the function terminates correctly, zero is returned; if an error occurs, a neg¬ 
ative error code is returned.This function returns these error codes: 

Error Description 

Code 

-1 System Error - Could not find tigalnk in the main tiga directory, 

either the tiga environment variable -m option is not set or that 
directory does not contain tigalnk . exe. 

-3 Out of Memory - Not enough host memory to run tigalnk or not 
enough TMS340 memory to store the ALM 

-4 Communication Driver not Running - Run tigacd 

-5 Graphics Manager not Running - Run tigalnk -ix 

-6 Missing RLM - Either the spelling of the RLM filename does not 
match the RLM filename in the current directory or the -i option of 
the TIGA environment variable is not set up. 

-7 Symboi Fiie Error- I/O error obtained in accessing the symbol file. 

The -m option of the TIGA environment variable is not set or the 
directory does not contain TIGA3 4 o.sYM or the file is corrupt. In the 
latter case recopy this file from your backup disk. 

-10 Symboi Reference - An unresolved symbol was referenced by the 
RLM. Determine the name either by producing a link map for the 
RLM or by invoking tigalnk from the command line using the -ec 
flag. 
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Create Absolute Load Module create aim 


Error Description (continued) 

Code 

-12 Symbol Table Mismatch - The modules installed in the symbol 
table do not match those the TIGA graphics manager has installed. 
Reinitialize the modules by a call to flush_extended and install 
them again. 
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Create_esyiTl Create External Symbol Table File 


Syntax int create_esym(gm_name) 

char far *gm_name; 

Type Core 

Description The create_esym function does not need to be called by the user. It is pro¬ 
vided as a procedural level interface to the linking loader. It should be used 
instead of calling the linking loader directly, to provide compatibility with fu¬ 
ture versions of TIGA. 

This function creates an external symbol table file from the supplied TIGA 
graphics manager file. If no file extension is supplied, then a file extension 
of .OUT is used. The external symbol table is saved under the name 
TIGA340. SYM. After Creation, this file will contain only the global (or external) 
symbols that were contained in the graphics manager file. During subse¬ 
quent installation of relocatable load modules, this file is used to resolve ex¬ 
ternal references. Also any external symbols contained in a RLM are added 
to this file during the installation process so those symbols can be refer¬ 
enced by other RLMs. 

If no pathname information is supplied for the gm_name, this function uses 
the path specified by the TIGA environment variable. The external symbol 
file created also uses this path information. For more details on extensibility, 
the use of this function refer to Chapter 4. 

If an error occurs, a negative error code is returned. If this function termi¬ 
nates normally, zero is returned. 

This function returns these 

Error Description 

Code 

-1 System Error - Could not find tigalnk in the main tiga directory, 

either the tiga environment variable -m option is not set or that di¬ 
rectory doesnotcontainTiGALNK.EXE. 

-4 Communications Driver not Running - Run tigacd. 

-5 Graphics Manager not Running - Run tigalnk -ix. 

-7 Symbol File Error - I/O error obtained in accessing symbol file. 
The -m option of the TIGA environment variable is not set or the di¬ 
rectory does not contain tiga340 . sym or the file is corrupt. In the 
latter case recopy this file from your backup disk. 

-11 COFF File not Absolute -The coFF file argument for this function 
is not linked to an absolute address. 
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Create External Symbol Table File create_esym 


Error Description (continued) 

Code 

-12 Symbol Table Mismatch - The modules installed In the symbol 
table do not match those the TIGA graphics manager has installed. 
Reinitialize the modules by a call to flush_extended and install 
them again. 
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delete font Delete a Font from Table 


Syntax 

Type 

Description 


int delete_font(id) 
short id; 

Extended 

The delete_font function removes from the font table the installed font ref¬ 
erenced by id. A nonzero value is returned if the font was successfully 
removed, and a value of zero if the font was not installed. Note that if the 
font removed was also the one selected for current text drawing operations, 
the system OEM font is selected. 
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Draw Line draw line 


Syntax 

Type 

Description 


void draw_line(xl, yl, x2, y2) 

short xl, yl; /* start coordinates */ 

short x2, y2; /* end coordinates */ 

Extended 

The drawjine function uses Bresenham’s algorithm to draw a line from the 
starting point to the ending point. xi and yi specify the starting coordinates; 
x 2 and y 2 specify the ending coordinates. The line is one pixel thick and is 
drawn in the current foreground color. 
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draw line Draw Line 


Example tinclude <typedefs.h> 

#include <tiga.h> 

#include <extend.h> 

CONFIG config; 

main() 

{ 

short xs, ys, xe, ye, i, color; 

if (set__videomode (TIGA, INIT | CLR_SCREEN) ) 

{ 

if (install_primitives0 >= 0) 

{ 

get_config(Sconfig); 
xs = config, mode. disp_hres»l; 
ys = config.mode .disp_vres»l; 
set_fcolor(RED); 

/* set up an add pixel processing option to affect */ 
/* overlapping lines in the center of the screen '^/ 
set_ppop(16); 

/* draw lines at diff. orientations */ 

for (xe =5, ye = 5; xe <= config.mode.disp_hres-6; 
xe += 17) 

draw_line(xs, ys, xe, ye); 
for (xe =5, ye = config.mode.disp_vres~6; 

xe <= config.mode.disp_hres-6; xe += 17) 
draw_line(xs, ys, xe, ye); 

for (xe = 5, ye = 10; ye <= config.mode.disp_vres-6; 
ye += 17) 

draw_line(xs, ys, xe, ye); 
for (xe = config.mode.disp_hres-6, ye = 10; 

ye <= config.mode.disp_vres-6; ye += 17) 
draw_line (xs, ys, xe, ye); 

} 

set_videomode(PREVIOUS, INIT); 

} 

} 
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Draw Ova! draw oval 


Syntax 

Type 

Description 


void draw_oval(w, h, xleft, ytop) 

short w, h; /* width, height of rect. */ 

short xleft, ytop; /* coordinates at top left corner */ 

Extended 

The draw_oval function draws the outline of an ellipse, given the minimum 
enclosing rectangle in which the ellipse is inscribed. The ellipse is in stan¬ 
dard position, with its major and minor axes parallel to the coordinate axes. 
The enclosing rectangle is defined by four arguments: 

□ The width w 

□ The height h 

□ The coordinates of the top left corner (xieft, ytop) 

The outline is one pixel thick and is drawn in the current foreground color. 
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draw_0vai Draw Oval 

Example #include <typedefs.h> 

#include <tiga.h> 

#include <extend.h> 

CONFIG config; 

mainO 

{ 

int vr, h, x, y; 

if (set___videomode (TIGA, INIT 1 CLR_SCREEN) ) 

{ 

if (install_primitives0 >= 0) 

{ 

get_config(Sconfig); 

/* restrict drawing to window in center of screen */ 
set_clip_rect (config.mode.disp_hres»l, 
config. mode. disp_vres»l, 
config. mode. disp_hres»2, 
conf ig.mode . disp_vres»2) ; 
set_fcolor(GREEN); 

/* draw various sizes ellipses */ 

for (w=0, x=4;w< config.mode.disp_hres/20; 

++W, X += w + 3) 

for (h=0, y=4; h< config.mode.disp_vres/20; 
++h, y += h + 3) 
draw_oval(w, h, x, y); 

} 

set_videomode(PREVIOUS, INIT); 

} 

} 
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Draw Oval Arc draw ovalarc 


Syntax void draw_ovalarc(w, h, xleft, ytop, theta, arc) 

short w, h; /* width and height */ 

short xleft, ytop; /* top left corner */ 

short theta; /* starting angle (degrees) */ 

short arc; /* angle extent (degrees) */ 

Type Extended 


Description The draw_ovalarc function draws an arc taken from an ellipse. The ellipse 
is in standard position, with the major and minor axes parallel to the coordi¬ 
nate axes. The arc is one pixel thick and is drawn in the current foreground 
color. 

The ellipse from which the arc is taken is specified in terms of the minimum 
enclosing rectangle in which it is inscribed. The first four arguments define 
the rectangle: 

□ The width w 

□ The height h 

□ The coordinates of the top left corner (xieft, ytop) 

The last two arguments define the limits of the arc: 

□ The starting angle, theta, is measured from the center of the right side 
of the enclosing rectangle and is treated as modulus 360. Positive 
angles are measured clockwise; negative angles are measured coun¬ 
terclockwise. 

□ The arc extent, arc, specifies the number of degrees (positive or nega¬ 
tive) spanned by the angle. If the arc extent is outside the range 
[-359,+359], the entire ellipse is drawn. 

Both arguments are expressed in degrees of elliptical arc, with 360 degrees 
representing one full rotation. 
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draw_OValarc Draw Oval Arc 

Example #include <typedefs.h> 

#include <tiga.h> 

#include <extend.h> 

CONFIG config; 

/* X coordinate of screen center */ 

#define XC (config.mode.disp__hres»l) 

/* y coordinate of screen center */ 

#define YC (config.mode.disp__vres»l) 

/* X coordinate of screen limit */ 

#define XMAX (config.mode.disp_hres-4) 

/* y coordinate of screen limit */ 

#define YMAX (config.mode.disp_vres-4) 

/* X increment */ 

#define DX (config.mode.disp_hres/40) 

/* y increment */ 

#define DY (config.mode.disp_vres/40) 

#define MAXBYTES 2048 

main () 

{ 

short w, h; 

PTR addr; 

if (set_videomode (TIGA, INIT | CLR_SCREEN) ) 

{ 

if (install_primitives0 >= 0) 

{ 

get_config(&config); 

/* draw a spiral 
set_f color(YELLOW); 

for (w = XMAX, h = YMAX; w > DX; h -= DY) 

{ 

draw__ovalarc (w, h, XC-w/2, YC-h/2, 0, 270); 
w -= DX; 

draw^ovalarc (w, h, XC-w/2, YC-h/2, 270, 90); 

} 

addr = gsp_malloc(MAXBYTES); 
set__f color (GREEN); 
seed_fill(XC, YC, addr, MAXBYTES); 
gsp__free (addr) ; 

} 

set_videomode(PREVIOUS, INIT); 

} 

} 
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Draw Pie Arc draw_piearc 


Syntax void draw_j5iearc(w, h, xleft, ytop, theta, arc) 

short w, h; /* width and height */ 

short xleft, ytop; /* top left corner */ 

short theta; /* starting angle (degrees) */ 

short arc; /* angle extend (degrees) */ 

Type Extended 


Description The draw_piearc function draws an arc taken from an ellipse. Two straight 
lines connect the two end points of the arc with the center of the ellipse. The 
ellipse is in the standard position, with the major and minor axes parallel to 
the coordinate axes. The arc and the two lines are all one pixel thick and are 
drawn in the current foreground color. 

The ellipse from which the arc is taken is specified in terms of the minimum 
enclosing rectangle in which it is inscribed. The first four arguments define 
the rectangle: 

□ The width w 

□ The height h 

□ The coordinates of the top left corner (xieft, ytop) 

The last two arguments define the limits of the arc: 

Q The starting angle, theta, is measured from the center of the right side 
of the enclosing rectangle, and is treated as modulus 360. Positive 
angles are measured clockwise; negative angles are measured coun¬ 
terclockwise. 

□ The arc extent, arc, specifies the number of degrees (positive or nega¬ 
tive) spanned by the angle. If the arc extent is outside the range 
[-359,+359], the entire ellipse is drawn. 

Both arguments are expressed in degrees of elliptical arc, with 360 degrees 
representing one full rotation. 

Example See patnfili_piearc 
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draw_point Draw Point 


Syntax 

Type 

Description 

Exampie 


void draw_point(x,y) 

short X, y; /* pixel coordinates */ 

Extended 

The draw_point function draws a single pixel. Arguments x and y give the 
XY coordinates of the designated pixel. The pixel is drawn in the current 
foreground color. 

#include <typedefs.h> 

#include <tiga.h> 

#include <extend.h> 

CONFIG config; 

main () 

{ 

int i, X, y, xy, yx; 

if (set_videomode(TIGA, INIT ! CLR_SCREEN)) 

{ 

if (install_primitives() >= 0) 

{ 

get_config(Sconfig); 
set_f color(CYAN); 

X = xy = 0; 

y = yx = conf ig.mode. disp_vres»l; 

/* draw Lissajous pattern in dots */ 

for (i = 1200; i > 0; —i) 

{ 

draw_point (x+(config.mode.disp_hres»l) , 
y+(config.mode.disp_vres»l) ) ; 

X += yx » 4; 
yx -= X » 4; 
y += xy » 5; 
xy -= y » 5; 

} 

} 

set_videomode(PREVIOUS, INIT); 

} 

} 
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Draw Polyline d raw_polyI i ne 


Syntax 


Type 

Description 


typedef struct 
{ 

short x; 
short y; 

}POINTS; 

void draw_polyline(n, pointo); 
short n; 

POINTS far ’^'points; 

Extended 

The draw__polyline function draws n single pixel-wide lines whose end¬ 
points are supplied in an array of structures, described in the syntax. 
Note that for the polygon drawn to be closed, the calling program must en¬ 
sure that the first and last points are the same. 

The function requires two input arguments: 

□ The first argument, n, defines the number of vertices in the polygon. 

□ The second argument, points, is an array in which each pair of adja¬ 
cent 16-bit quantities contains the X and Y coordinates, respectively, of 
a vertex. 

The argument points can be of any length. The application can easily 
overflow the command buffer used by the host processor to send the 
function parameters to the TMS340. The size of the command buffer is in 
the CONFIG structure (described in Appendix A) returned by the get_con- 
fig function. The application must check that the data sent will not overflow 
this buffer. 


The number of points that can be sent is given by the following formula: 


n < 


com_buffer_size (in bytes) -10 


4 


An alternate entry point draw__polyline_a with the same parameterization 
is supplied to check the size of the data to be sent. If the command buffer 
overflows, draw_polyllne_a attempts to allocate a temporary buffer in 
heap. In this way, the application is freed from having to check the size of 
the data being transferred; however, the invocation of the function takes 
longer, because the length of the data must be parsed. If there is not enough 
room to store the temporary buffer in TMS340 memory, the error function 
is invoked (which can be trapped by the install_usererror function). 
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drawjpolyiine Draw Polyline 


Example #include <typedefs.h> 
#include <tiga.h> 
#inclucie <extend.h> 


CONFIG config; 


/* screen 
short far 
{ 

-2,+l, 

- 2 ,- 2 , 


independent coordinates of a cube 
cube [ ] = 

-2,-2, -1,-1, -l,+2, -2,+l, 

+ 1 ,- 2 , + 2 ,- 1 , - 1 ,- 1 , - 2 ,- 2 , 

+2,-1, +2,+2, —l,+2, -1,-1, 


main () 

{ 

int dx, dy, i; 


*/ 


if (set__videomode (TIGA, INIT | CLR_SCREEN) ) 

{ 

if (install_primitives0 >= 0) 

{ 

get_config(Sconfig); 
set_fcolor(MAGENTA); 
dx = config.mode .disp_hres»4; 
dy = config. mode. disp_vres»4; 

/* scale cube coordinates to fit the resolution */ 
for (i =0; i < sizeof(cube)/sizeof(short); ) 

{ 

cube[i++] *= dx; 
cube[i++] *= dy; 

} 

/* move draw origin to the center of the screen */ 
set_draw__origin (config.mode.disp_hres»l, 
config.mode.disp_vres»l) ; 

/* draw the outline of the cube */ 

drawjpolyiine((sizeof(cube)/sizeof(short))»1,cube); 

} 

setjVideomode (PREVIOUS, INIT); 

} 

} 
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Draw Rectangle Clraw_reCt 


Syntax void draw_rect(w, h, xleft, ytop) 

short w, h; /* width and height of rectangle */ 

short xleft, ytop; /* coordinates at top left corner */ 

Type Extended 

Description The draw_rect function draws the outline of a rectangle. The first four argu¬ 
ments define the rectangle: 

□ The width w 

□ The height h 

□ The coordinates of the top left corner (xleft, ytop) 

The outline is one pixel wide and is drawn in the current foreground color. 

The draw_rect function is equivalent to the following four calls to the 
drawjine function: 

draw_line(xleft, ytop, xleft+w, ytop); 
draw_line(xleft, ytop+h, xleft+w, ytop+h); 
draw__line (xleft, ytop+1, xleft, ytop+h-2) ; 
draw_line(xleft+w, ytop+1, xleft+w, ytop+h~2); 
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field_extract Extract Data from GSP Memory 


Syntax 

Type 

Description 


unsigned long field_extract(gptr,fs) 

unsigned long gptr; /* pointer to GSP memory address 

unsigned short fs; /* field size */ 

Core 

The field_extract function returns the 32-bit, zero-extended data from the 
TMS340 memory address specified by gptr. The field size parameter f s 
must be between 1 and 32 inclusive and specifies the number of bits to read 
from TMS340 memory. There are no restrictions on the alignment of the 
TMS340 address. 
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Insert Data into GSP Memory field_insert 


Syntax 

Type 

Description 


void field_insert(gptr,fs,data) 

unsigned long gptr; /* pointer to GSP memory address */ 

unsigned short fs; /* field size */ 

unsigned long data; /* data to be inserted */ 

Core 

The fieidjnsert function writes the value of data into the TMS340 memory 
specified by gptr. The field size parameter f s must be between 1 and 32 
inclusive and specifies the number of bits to be written. Bit 0 (the least 
significant bit) of data is written first, followed by bit 1 and so on until the 
specified number of bits have been written. There are no restrictions as to 
the alignment of the TMS340 address. 
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fill_COnvex FHI Convex Polygon 


Syntax typedef struct 

{ 

short x; 
short y; 

}POINTS; 

void fill_convex(n, points); 
short n; 

POINTS far ^points; 

Type Extended 

Description The fill_convex function fills a convex polygon, given a iist of points repre¬ 
senting the vertices. To be drawn correctiy, the polygon must have at least 
three vertices visible. The first and last points must be the same to ensure 
that the poiygon is closed. The polygon is soiid-filied with the current fore¬ 
ground color. 

The function requires two input arguments: 

□ The first argument, n, defines the number of vertices in the polygon. 

□ The second argument, points, is an array in which each pair of adja¬ 
cent 16-bit quantities contains the X and Y coordinates, respectively, of 
a vertex. 

fill_convex is similar to the fill_polygon function, but is speciaiized for rap¬ 
id drawing of convex polygons. It also executes more rapidly and supports 
realtime applications, such as animation. 

The fill_convex function automaticaiiy culis back faces to support 3-D 
appiications. A polygon is drawn oniy if its front side is visibie, that is, if it is 
facing toward the screen, if the vertices are specified in counterclockwise 
order, the poiygon is assumed to be facing away from the screen and is 
therefore not drawn. 

The back face test is done by first comparing vertices n -2, n -1, and 0 to 
determine whether the polygon vertices are specified in ciockwise (front 
face) or counterciockwise (back face) order. This test assumes the polygon 
contains no concavities, if the three vertices are coiinear, the back face test 
is made again using the next three vertices, n-1,0, and 1. The test repeats 
until three vertices are not coiinear. if ali the vertices are coiinear, the poiy¬ 
gon is invisibie. 

One of the parameters of fill_convex is a list of points that can be of any 
length. The application can easily overfiow the command buffer used by the 
host processor to send the function parameters to the TMS340. The size of 
the command buffer is in the CONFIG structure (described in Appendix A) 
returned by the get_config function. The appiication must check that the 
data sent will not overflow this buffer. 
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Fill Convex Polygon fill_COnvex 

The number of points that can be sent is given by the foliowing formula: 

com_buffer_size (in bytes) -10 

n < - 

4 

An alternate entry point fill_convex_a, with the same parameterization, is 
supplied to check the size of the data to be sent. If the command buffer 
overflows, flll_convex_a attempts to allocate a temporary buffer in heap. 
In this way, the application is freed from having to check the size of the data 
being transferred; the invocation of the function takes longer, because the 
length of the data must be parsed. If there is not enough room to store the 
temporary buffer in TMS340 memory, the error function is invoked (which 
can be trapped by the install_usererror function). 
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fill oval Fill Oval 


Syntax 

Type 

Description 

Exampie 


void fill_oval(w, h, xleft, ytop) 

short w, h; /* width, height of rect. */ 

short xleft, ytop; /* coordinates of top left corner */ 

Extended 

The fin_oval function draws an ellipse solid-filled with the current fore¬ 
ground color. The ellipse is in standard position, with its major and minor 
axes parallel to the coordinate axes. 

The ellipse is defined by the minimum enclosing rectangle in which it is in¬ 
scribed. The first four arguments define the rectangle: 

□ The width w 

□ The height h 

□ The coordinates of the top left corner (xleft, ytop) 

See draw oval 
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Fill Pie Arc fill_piearc 


SyntSX void fill_piearc(w, h, xleft, ytop, theta, arc) 

short w, h; /* width and height */ 

short xleft, ytop; /* top left corner */ 

short theta; /* starting angle (degrees) */ 

short arc; /* extent of angle (degrees) */ 

Type Extended 


Description The fill_piearc function draws a pie-shaped wedge solid-filled with the cur¬ 
rent foreground color. The wedge is bounded by an arc and two straight 
edges. The arc is taken from an ellipse in standard position, with its major 
and minor axes parallel to the coordinate axes. The two straight edges are 
defined by lines connecting the end points of the arc with the center of the 
ellipse. 

The ellipse from which the arc is taken is specified in terms of the minimum 
enclosing rectangle in which it is inscribed. The first four arguments define 
the rectangle: 

□ The width w 

□ The height h 

□ The coordinates of the top left corner (xieft, ytop) 

The last two arguments define the limits of the arc: 

□ The starting angle, theta, is measured from the center of the right side 
of the enclosing rectangle and is treated as modulus 360. Positive 
angles are measured clockwise: negative angles are measured coun¬ 
terclockwise. 

□ The arc extent, arc, specifies the number of degrees (positive or nega¬ 
tive) spanned by the angle. If the arc extent is outside the range 
[-359,+359], the entire ellipse is drawn. 

Both arguments are expressed in degrees of elliptical arc, with 360 degrees 
representing one full rotation. 

Example See patnfill_piearc 
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fill_polygon FHI Polygon 


Syntax 


Type 

Description 


typedef struct 
{ 

short x; 
short y; 
}POINTS; 


void fill_polygon(n, points); 
short n; 

POINTS far ^points; 

Extended 

The fill_polygon function fills a polygon, given a list of endpoints of the 
polygon. No restrictions are placed on the shape of the polygons filled by 
this function: edges can cross each other, filled areas can contain holes, and 
two or more filled regions can be disconnected from each other. The poly¬ 
gon is solid-filled with the current foreground color. Note that the first and 
last points of the array should be the same to close the polygon. 

The function requires two input arguments: 

Q The first argument, n, defines the number of vertices in the polygon. 

□ The second argument, points, is an array in which each pair of adja¬ 
cent 16-bit quantities contains the X and Y coordinates, respectively, of 
a vertex. 

This function also takes as an implied argument a 1-bit representation of 
the frame buffer, which it uses as a temporary workspace. This workspace 
must be set up priorto invoking this function (via a call to the set_wksp func¬ 
tion). 

The argument points can be of any length. The application can easily 
overflow the command buffer used by the host processor to send the 
function parameters to the TMS340. The size of the command buffer is in 
the CONFIG structure (described in Appendix A) returned by the get_con- 
fig function. The application must check that the data sent will not overflow 
this buffer. 

The number of points that can be sent is given by the following formula: 
com_b>Jffer_size (in bytes) -10 


An alternate entry point fill_polygon_a, with the same parameterization, 
is supplied to check the size of the data to be sent. If the command buffer 
overflows fill_polygon_a attempts to allocate a temporary buffer in heap. 
In this way, the application is freed from having to check the size of the data 
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Fill Polygon fill_polygon 


being transferred: however, the invocation of the function takes longer 
because the length of the data has to be parsed. If there is not enough room 
to store the temporary buffer in TMS340 memory, the error function is 
invoked (which can be trapped by the install_usererror function). 
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fill_polygon Fill Polygon 


ssssssss# 


Example #include <typedefs.h> 

#include <tiga.h> 

#include <extend.h> 

CONFIG config; 

/* screen independent coordinates of a cube */ 

short far cubel[] = {-2,+l, -2,-2, -1,-1, -l,+2, -2, +1}; 

short far cube2[] = {-2,-2, +1,-2, +2,-1, -1,-1, -2,-2,}; 

short far cube3[] = {-1,-1, +2,-1, +2,+2, -l,+2, -1,-1,}; 

main() 

{ 

PTR w}csp, pitch; 
int dx, dy, i; 

if (set__videomode (TIGA, INIT 1 CLR_SCREEN) ) 

{ 

if (install_j?rimitives () >= 0) 

{ 

/* see if wJcsp allocated */ 

get_config(Sconfig); 

if (!get_wksp(&wksp, &pitch)) 

{ 

/* workspace not set up in offscreen memory, */ 

/"Use lualloc to create it "/ 

pitch = l«lmo (config.mode. disp_hres) ; 
if (pitch < config.mode .disp_hres) pitch «= 1; 
wksp = gsp_malloc(((pitch * config.mode.disp_vres) 

+ 7) / 8); 

set_wksp(wksp, pitch); 

} 

dx = config. mode. disp_hres»4; 
dy = config. mode. disp__vres»4; 

/* scale cube coordinates to fit the resolution */ 
for (i =0; i < sizeof(cubel)/sizeof(short); ) 

{ 


cubel[i++] 


dx; 

cubel[i—] 


dy; 

cube2[i++] 

•k = 

dx; 

cube2[i—] 

* = 

dy; 

cubes[i++] 


dx; 

cubes[i++] 


dy; 


} 
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Fill Polygon fill_polygon 

/* move draw origin to the centre of the screen */ 
set_draw_origin (config.mode.disp_hres»l, 
config.mode.disp_vres»l) ; 

/* fill in the sides of the cube */ 

set_fcolor(BLUE); 

fill_polygon((sizeof(cubel)/sizeof(short))»1, 
cubel); 

set_fcolor(LIGHT_BLUE); 

fill_polygon((sizeof(cube2)/sizeof(short))>>1, 
cube2); 

set_fcolor(CYAN); 

fill_polygon((sizeof(cubeS)/sizeof(short))>>1, 


set_videomode(PREVIOUS, INIT); 

} 

} 
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f ill_rect Fill Rectangle 


Syntax 

Type 

Description 

Exampie 


void fill_rect(w, xleft, ytop) 

short w, h; /* width and height of rectangle */ 

short xleft, ytop /* XY coords at top left corner */ 

Extended 

The fill_rect function draws a rectangle solid-filled with the current fore¬ 
ground color. The first four arguments define the rectangle: 

Q The width w 

□ The height h 

□ The coordinates of the top left corner (xieft, ytop) 

See bitbIt 
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Syntax 

Type 

Description 


Flush External Symbol Table File f lush_esym 


int flush_esym() 

Core 

The flush_esym function does not need to be called by the application. It 
is a procedural level interface to the iinking ioader. It should be used instead 
of caliing the linking loader directly to provide compatibiiity with future ver¬ 
sions of TIGA. 

This function flushes the external symbols from the symbol table 
TIGA340. SYM, leaving just the globai symbols in this fiie. 

For more details on extensibility and the use of this function, refer to Chapter 
4. 

If the function terminates correctiy zero is returned; if an error occurs, a neg¬ 
ative error code is returned.This function returns these error codes; 

Error Description 

Code 

-1 System Error - Could not find tigalnk in the main TIGA directory, 

either the TIGA environment variable -m option is not set or that 
directory does not contain tigalnk.exe. 

-4 Communications Driver not Running - Run tigacd 

-5 Graphics Manager not Running - Run tigalnk -ix 

-7 Symbol File Error - I/O error obtained in accessing symboi file. 
The -m option of the TIGA environment variable is not set or the 
directory does not contain tiga 3 4 o. sym or the file is corrupt. In the 
latter case, recopy this file from your backup disk. 
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flush_extended Flush ah user Extensions 

Syntax void flush_extended() 

Type Core 

Description The flush_extended function performs two operations: first, it flushes the 
TiGA extended primitives and the installed userfunctions (both direct mode 
and C-packet) on the TMS340 side. Second, it removes the symbol table 
information stored on the host side. You can then install a new set of user 
functions. 

For more details on extensibility and the use of this function, referto Chapter 
4. 
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TIGA Application Interface 



Fill Frame Oval frame OVal 


Syntax 

Type 

Description 


Exampie 


void fraine_oval (w, h, xleft, ytop, dx, dy) 

short w, h; /* width, height of rect. */ 

short xleft, ytop; /* coordinates at top left corner */ 

short dx, dy; /* width, height of frame border */ 

Extended 

The fraine_oval function solid-fills an ellipse-shaped frame with the current 
foreground color. The frame consists of a filled region between two concen¬ 
tric ellipses. The portion of the screen enclosed by the frame is not altered. 

The outer ellipse is specified in terms of the minimum enclosing rectangle 
in which it is circumscribed. The first four arguments define the rectangle: 

□ The width w 

□ The height h 

□ The coordinates of the top left corner (xieft, ytop) 

The thickness of the frame in the X and Y dimensions is defined by two addi¬ 
tional arguments: 

□ dx specifies the horizontal distance between the outer and inner el¬ 
lipses. 

□ dy specifies the vertical distance between the outer and inner ellipses. 

See patnfili_piearc. 
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f raine_rect FHI Frame Rectangle 


Syntax void frame_rect(w, h, xleft, ytop, dx, dy) 

short w, h; /* width,height of enclosing rect. */ 

short xleft, ytop; /* coordinates at top left corner */ 

short dx, dy /* width, height of frame border */ 

Type Extended 

Description The fraitie_rect function solid fills a rectangular shaped frame with the cur¬ 
rent foreground color. The frame consists of a filled region between two con¬ 
centric rectangles. The portion of the screen enclosed by the frame is not 
altered. 

The outer rectangle is specified in terms of the minimum enclosing rectangle 
in which it is inscribed. The first four arguments define the rectangle: 

□ The width w 
Q The height h 

□ The coordinates of the top left corner (xleft, ytop) 

The thickness of the frame in the X and Y dimensions is defined by two addi¬ 
tional arguments: 

□ dx specifies the horizontal distance between the outer and inner rect¬ 
angles. 

□ dy specifies the vertical distance between the outer and inner rectan¬ 
gles. 
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Return if a Given Function is Implemented function_implemented 


Syntax 

Type 

Description 


int function_implemented(function_code) 
short function_code; 

Core 

The functionjmplemented function queries whether a function is implem¬ 
ented or not. Functions in TIGA have an associated function code; some 
may not be implemented on every board,. 

The following functions are not likely to be implemented on all boards and 
should be queried with functionjmplemented before being invoked: 

cop2gsp 

set jalet 

get_palet 

set_palet_entry 

get_palet_entry 

set_transp 

gsp2cop 

init_palet 

The function codes themselves are contained in the main TIGA insert file, 
which contains the type and function declarations. The function codes are 
#defined to be the same as the function name but in upper case. Thus, the 
syntax to inquire if set_palet is implemented is 

if(function_implemented(SET_PALET)) 

{ 


} 
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function_implementecl Return if a Given Function is impiemented 


Example #include <typedefs.h> 

#include <tiga.h> 

#include <extend.h> 

CONFIG config; 

main() 

{ 

short green_index; 

if (set_videomode(TIGA, INIT | CLR_SCREEN)) 

{ 

if it is possible to set the palet entry value, */ 
/* set it to bright green */ 

if (function_implemented (SET_PALET_ENTRY) ) 

{ 

green__index = 1; 

set_palet_entry(green_index, 0, OxFF, 0, 0); 

} 

else 

{ 

/■* if it is not possible to set the palet entry, '^/ 
/* (as in the case of a ROM-based palette) 

/* then get the index of the brightest green */ 

green_index - get_nearest_color(0, OxFF, 0, 0)/ 

} 

/” use index to clear the screen to */ 

clear_screen(green_index); 
set_videomode(PREVIOUS, INIT); 

} 

} 
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TiGA Appiication interface 



Return Foreground and Background Colors get_COlors 


Syntax 

Type 

Description 


void get_colors(fcolor, bcolor) 
short far *fcolor; 
short far *bcolor; 

Core 

The get_colors function returns both the foreground and background col¬ 
ors. 
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get_COnfig Return Board Configuration 


Syntax 

r - 

/* MODEINFO structure definition with the current mode of operation 

r --- 

typedef struct 

{ 

long disp_pitch; 
short disp___vres; 
short disp_hres 
short screen_wide 
short screen_high; 
short disp_psize; 
long pixel_mask; 
short palet_gun_depth; 
long palet_size; 
short palet_inset; 
short num_pages; 
short num_offscrn_areas; 
long wksp_addr; 
long wksp_pitch; 

}MODEINFO; 

/* - 

/* CONFIG structure definition of the current hardware configuration 

/* - 


V 

V 

V 


V 

V 

V 


typedef struct 

{ 

short version_nuniber; 
long comm_buff_size; 
long sys_flags; 
long device_rev; 
short num_modes; 
short current_mode; 
long program_mem_start; 
long program_mem__end; 
long display_mem_start; 
long display__mem_end; 
long stack__size; 
long shared_mem_size; 
char far ’^shared_host_addr; 
PTR shared_gsp_addr; 
MODEINFO mode; 

}CONFIG; 


void get_config(config) 
CONFIG far *config; 
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Return Board Configuration g0t__COnfig 

Type Core 

Description The get_config function returns a structure containing ali board- and 
mode-specific information. Note that it is very likely that the structure de¬ 
scribed above will change in subsequent revisions. Therefore, it is recom¬ 
mended that the elements of the structure be referenced symbolically by 
their field name, rather than as an offset to the start of the structure. Insert 
files are available to do this. 

The fields are as follows: 

version_number TIGA revision number, assigned by Texas Instru¬ 
ments. 

coinm_buf f_size Size, in bytes, of the communications buffer; applica¬ 

tion needs to ensure that the data sent does not 
overflow this buffer, for commands which do not 
check the size of the downloaded data. 

sys flags Bits 0 — 7 indicate Fioating Point Units (FPUs) are 

present, in order to be compatible with the 
TMS34020 Coprocessor ID codes. Bits 8—15 are re¬ 
served. 

device__rev This function invokes the TMS340’s REV instruction 

and return its result here. 

num_modes Number of extended modes for boards that allow the 

switching between different display setups. 

cur r ent_mode Mode number corresponding to the current operating 

mode. 

prograin_mem_start Start address of program memory. 
program_mem_end End address of program memory. 
dispiay_mem._start Start address of display memory. 
dispiay_mem_end End address of display memory. 
stack_size Default stack size can be modified using gsp_nninit. 

s ha r e_mem__s i z e Size (in bytes) of shared memory that is available for 

the application to use. 

share_host_addr If share_size is nonzero, this is the start address in 
host memory of the shared memory; otherwise it is 
undefined. 

share_gsp_addr If share_size is nonzero, this is the start address in 
TMS340 memory of the shared memory; otherwise, 
it is undefined. 
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get_COnfig Return Board Configuration 

disp_pitch Display pitch: linear difference between two scan 

lines in bits. 

disp_vres Vertical resolution in scan lines. 

disp_hres Horizontal resolution in pixels. 

screen_wide Contains the width of the monitor in centimeters. For 

systems where these dimensions are unknown, set 
to zero. 

screen_high Containsthe height ofthe monitor in Centimeters. For 

systems where these dimensions are unknown, set 
to zero. 

disp_psize Pixel size. 

pixei_mask Contains a mask of the bits used in a pixel. It normally 

contains the value of 2 to the power disp_psize minus 
1, indicating that every bit of pixel data is pertinent. 
On some boards the frame buffer may be arranged 
by 8 (disp_psize = 8) but with only 6 bits implemented. 
In that case pixel mask would contain the value 63 
(hexadecimal 3F). 

paiet_gun_depth Number of bits per gun in palette. 

paiet_size Number of entries in the palette. 

paiet inset For most systems this field is set to 0. For 

TMS34070-based boards that store the palette in the 
frame buffer, this is the offset from the start of the scan 
line to the first pixel data. 

num_j)ages Number of display pages in multi-buffered systems. 

num_o f f s c r n__a r e a s This is the number of offscreen memory blocks avail¬ 
able. If nonzero, then it is used to allocate space for 
the offscreen array, which can be obtained from the 
TMS340 via a call to the get_offscreen_memory 
function. 

wksp_addr Starting linear address in memory of offscreen work¬ 

space area. 

wksp_pitch Pitch of offscreen workspace area. If wksp_pitch=0, 

then no offscreen workspace is currently allocated. 

Example See draw line. 
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Return Current Cursor State get_curs_state 


Syntax 

Type 

Description 

Exampie 


int get__curs_state () 

Core 

The get_curs_state routine returns true (nonzero) if the cursor is enabied, 
false otherwise. 

See cursor manipulation in set_curs_shape. 
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get_CUrS_xy Return Current Cursor Position 


Syntax 

Type 

Description 

Exampie 


void get_curs_xy(px, py) 
short far *px; 
short far *py; 

Core 

The get_curs_xy returns the pixel coordinates of the cursor hotspot. 
Note that the coordinates are relative to the left corner of the screen, not 
to the drawing origin. 

See cursor manipulation in set_curs_shape. 
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Return Current Graphics Environment get_env 


Syntax 


Type 

Description 


typedef 

{ 

long 

struct 

xyorigin; 

long 

pensize; 

long 

patnaddr; 

long 

srcbm; 

long 

dstbm; 

unsigned long stylemask 


} ENVIRONMENT; 


void get_env(env) 

ENVIRONMENT far ^env; 

Extended 


The get_env function takes as its argument a pointer to the ENVIRON¬ 
MENT structure containing the graphics environment variables. Although 
there are functions to manipuiate these variables individually, if required, 
this function can be used to return the entire environment. Note that the 
structure described above may change in subsequent revisions. Therefore, 
it is recommended that the elements of the structure be referenced symboli¬ 
cally by their field name, rather than as an offset to the start of the structure. 
Insert files are available to do this.The fields of this structure are as follows: 


xyorigin 

pensize 

patnaddr 

srcbm 

dstbm 

stylemask 


Current drawing origin in y::x format set by set_draw_origin. 
Current pen size arranged in y::x format, set by set_pensize. 
TMS340 address of current pattern, set by set_patnaddr. 

TMS340 address of current source bitmap structure, set by 

set_srcbm. 

TMS340 address of current destination bitmap structure, set 

by set_dstbm. 

Current line style mask used by styledjine function. 
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get__fontinfO Return Installed Font Information 


Syntax typedef struct 
{ 

char facename[32]; 

short first; /* ASCII code of first character */ 

short last; /* ASCII code of last character */ 

short maxwide; /* maximum character width / 

short avgwide; /* average width of characters */ 

short maxkern; /* max character kerning amount */ 

short charwide; /* character width (O=proportional) */ 

short charhigh; /* character height */ 

short ascent; /* ascent (how far above base line) */ 

short descent; /* descent (how far below base line) */ 

short leading; /* Idng. (row bottom to next row top) */ 

long fontptr; /* font address in GSP memory */ 

short id; /* id of font (set at install time) */ 

}F0NTIN£-’0; 


int get_fontinfo(id, pFontInfo) 
short id; 

FONTINFO far *pFontInfo; 

Type Core 

Description The get_fontinfo function copies a structure of type FONTINFO, which de¬ 
scribes the physical characteristics of the installed font referenced by id 
into the structure pointed to by pFontinfo. A nonzero value is returned if 
the structure is successfully copied; zero otherwise. An id of zero returns 
the FONTINFO structure for the system font, which does not need to be 
installed. If id is specified as -1, the FONTINFO of the currently selected 
font is returned. 
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Return Interrupt Service Routine Priorities g©t_isr_priorities 


Syntax 

Type 

Description 


void get_isr_priorities(numisrs, ptr) 

short numisrs; /* number of isrs */ 

short far *ptr; /* pointer to array of shorts */ 

Core 

The getJsr_priorities function returns the priorities assigned when install¬ 
ing interrupt service routines (ISRs) using the install_rlm or install_alm 
functions. The calling function must ensure that enough space is allocated 
to hold all returned priority information. 

There is a one-to-one correspondence between an ISR and its associated 
priority. The first priority returned corresponds to the first ISR installed and 
so on. 

After calling this function, all priority data is flushed internally within TIGA, 
thereby enabling new priority data to be collected the next time install_alm 
or instali_rlin is called to install an ISR. 

For more details on extensibility and the use of this function, referto Chapter 

4. 
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get_fnodeinfo Return Board Configuration 

Syntax int get_modeinfo(index, modeinfo) 

short index; 

MODEINFO far *modeinfo; 

Type Core 

Description The get_modeinfo function returns a structure containing a possibie board 
configuration supported by the current board and monitor. The MODEINFO 
structure is described in detail in the get_config function. The index param¬ 
eter is used to cycle through the different modes by setting it to 0,1,2, etc. 
It returns the MODEINFO structure for modes 0,1,2, etc. if an invalid index 
is entered, the function returns false (zero); othenwise, it returns true. The 
total number of possible modes can be found from the CONFIG structure 
using the get_config function. 
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Return Nearest Color in a Palette get_nearest_COlor 


Syntax 


Type 

Description 


Example 


long get_nearest_color(r, g, b, i) 
char r; 
char g; 
char b; 
char i; 

Core 

The get_nearest_color function searches the current palette and detects 
the closest color value to that specified by the parameters. For a mono¬ 
chrome palette, it is simply the first index closest toi. For color palettes, 
the function is more complicated. Weighting values are given to each index 
that are the sum of the differences between the parameter r and the color’s 
red value, and the difference between the parameter g and the color’s green 
value, etc. Then the index with the smallest weight value is returned. See 
also Appendix B.7 for details on color selection. 

See functionjmplemented. 
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get_OffSCreen_memory Return Offscreen Memory Blocks 


Syntax 


Type 

Description 


typedef struct 
{ 

long addr; 
short xext; 
short yext; 

}OFFSCREEN_AREA; 

void get_offscreen_memory(num_blocks, offscreen) 
short num_blocks; 

OFFSCREEN_AREA far ’^offscreen; 

Core 

The get_offscreen_memory function returns the description of the off¬ 
screen memory biocks found in the system for the appiication to use. These 
blocks generally consist of display memory not being used either for the 
frame buffer or for an aiternate page of frame buffer in multiple buffer sys¬ 
tems. The number of blocks is in the structure returned in get_config. The 
appiication must reserve enough room for that amount of offscreen entries 
by first calling Microsoft’s C malloc. The address returned by malloc shouid 
be submitted as the parameter to this function, as weli as the number of 
blocks to be returned. 


The structure returned consists of the start address of the TMS340 off¬ 
screen block, plus xext and yext in pixels. 


These offscreen blocks can be used as temporary workspace for functions 
such as set_wksp, seed_fill and zoom_rect. Note that no memory man¬ 
agement is performed on these blocks. The application must ensure the va¬ 
lidity of the data stored there. Note aiso that the offscreen memory blocks 
are completely separate from those used by the memory management func¬ 
tions such as gsp_mailoc. 


If an offscreen memory block is used as the default offscreen workspace, 
it is guaranteed to be the first block returned via the 
get_offscreen_meinory function. 
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Return Offscreen Memory Blocks get_Offscreen_memory 


EXBinple tinclude <malloc.h> 

#include <typedefs.h> 

#include <tiga.h> 

#include <extend.h> 

CONFIG config; 

short arrow_shape [ ] == 

{ 

0x0003, 0x0007, OxOOOF, OxOOlF, OxOOSF, 0x007F, OxOOFF, OxOlFF, 

0x03FF, OxOlFF, 0x007F, 0x00F7, 0x00F2, OxOlEO, OxOlEO, OxOOCO 

}; 

#define ARROW_W 16 
#define ARROW_H 16 

main () 

{ 

int i; 

PTR arrow_addr; 
long arrow_size; 

OFFSCREEN_AREA far *offscreen; 

if (set_videomode(TIGA, INIT 1 CLR_SCREEN)) 

{ 

if (install_primitives0 >= 0) 

{ 

get_config(Sconfig); 
arrow_addr = 0; 

/* check if any offscreen areas are big enough */ 

if (config.mode.num_offscrn_areas) 

{ 

/* malloc space in host memory to hold offscreen */ 
/* structure */ 

offscreen = (OFFSGREENWAREA *)malloc 
(config.mode.num_offscrn_areas 
*sizeof(OFFSCREEN_AREA)); 

/* get the offscreen memory data structure */ 

get_offscreen__memory (config.mode.num_offscrn___areas, 
offscreen); 
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get_OffSCreen_tTiemoty Return Offscreen Memory Blocks 


/* define size needed to store the arrow in bits 
arrow_size = ARROW_W * ARROW_H; 

for (i = 0; (i < config.mode.num_offscrn_areas) && 

(!arrow_addr); i++) 

{ 

if ((offscreen[i].xext * config.mode.disp_psize) 
>arrow_size) 

arrow_addr=offscreen[i].addr; 

} 

} 

/* if no available offscreen memory, use gsp_malloc */ 
if (!arrow_addr) 

arrow_addr = gsp_malloc((arrow_size+7) /8) ; 

/* transfer shape data from host to gsp '^Z 

host2gsp((uchar far *) arrow_shape, arrow_addr, 
{arrow__size+7)/8, 0) ; 

/* set the source bitmap to the arrow shape */ 

set_srcbm(arrow_addr, ARROW_W, ARROW_W, ARROW_H, 1); 

Z* blit the arrow to top-left corner of the screen, *Z 
/* performing expand of 1 to n bits-per-pixel */ 

set_colors (LIGHT_GRAY, DARK_GRAY); 
bitblt(ARR0W_W, ARROW_H, 0, 0, 0, 0); 

} 

set__videomode (PREVIOUS, INIT) ; 

} 

} 
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Read an Entire Palette get_palet 


Syntax 


Type 

Description 


Exampie 


typedef struct; 

{ 

char r: 
char g; 
char b: 
char i; 

}PALET; 

void get_palet(palet_size, palet) 
short palet_size; 

PALET far *palet; 

Core 

The get_palet function reads an entire paiette into the paiet array. The 
paiet size parameter should be the same as the entry in the CONFIG 
structure to return the entire palette into the paiet array defined in host 
memory. 

Note that the paiet values returned are the physical colors used in the pal¬ 
ette on the board. If a paiette hexadecimal entry is set by the set_palet or 
set_palet_entry functions to 

Red = FF 

Green = FF 

Blue = FF 

Intensity = OF 

With the actual color palet using only 4 bits per gun, the hexadecimal values 
read by a call to get_palet or get_palet_entry are 

Red = FO 

Green = FO 

Blue = FO 

Intensity = 00 

See also Appendix B.7 for details on color selection. 

See call to get_palet_entry. 
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get_^alet_entl7 Return a Palette Entry 


Syntax int get_palet_entry(index, r, g, b, i) 

long index; 
char far *r; 
char far *g; 
char far *b; 
char far *i; 

Type Core 

Description The get_palet_entry routine returns the r, g, b, and i entries for a 
given entry in the palette. If the index is in the valid range, this function re¬ 
turns true (nonzero) and the palette entry. If the index is invalid, the values 
returned are also invalid, and the function returns false (zero). 
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Return a Palette Entry get_palet_entry 


Example #include <tYpedefs.h> 

#include <tiga.h> 

#include <extend.h> 

CONFIG config; 

main() 

{ 

char r, gl, g2, b, i; 

if (set_videomode(TIGA, INIT ! CLR_SCREEN)) 

{ 

if (install_primitives() >= 0) 

{ 

get_config(&config); 

if (function_implemented (SET_PALET_ENTRY) ) 

{ 

/* set two logical colors, shades of green '^/ 

set_palet_entry(1, 0, OxFF, 0, 0); 
set_palet_entry(2, 0, OxFO, 0, 0) ; 

/* get the physical colors back */ 

get_palet_entry(1, &r, &gl, &b, &i); 
get_palet_entry(2, &r, &g2, &b, &i) ; 

/* if green values are the same,use blue instead 
if (gl == g2) 

{ 

set_palet_entry(2, 0, 0, OxFF, 0); 

} 

/* fill some rects based on these colors */ 

set_fcolor(1); 

fill_rect (config.mode . disp_hres»l, 

config .mode . disp_vres»l, 0, 0); 
set_f color (2) ; 

f ill_rect (config.mode . disp_hres»l, 
config. mode. disp_vres»l, 
config. mode. disp_hres»l, 
config.mode.disp_vres»l) ; 

/* restore the palet */ 

init_palet(); 

} 

} 

set__videomode (PREVIOUS, INIT) ; 

} 

} 
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get_pixel Return Pixel Value 


Syntax 

Type 

Description 


long get_pixel(x, y) 

short X, y; /* coordinates of pixel */ 

Extended 

The get_pixel function returns the value of the pixel at coordinates (x, y). 
The coordinates are relative to the drawing origin. Given a pixel size of /? bits, 
the pixel is contained in the n LSBs of the return value (the MSBs are Os). 
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Return Plane Mask get_pmask 


Syntax long get_pinask () ; 

Type Core 

Description The get_pmask function returns the value of the plane mask (GSP PMASK 
register). Although only the 16 LSBs of the PMASK register are im¬ 
plemented in the TMS34010, the plane mask is 32 bits to provide upward 
compatibility with future TMS340 processors. 

The plane mask designates which bits within a pixel are protected against 
writes, and affects all operations on pixels. The protected bits are replicated 
for each pixel throughout the 32-bit plane mask. The 1 s in the plane mask 
specify protected bits in the destination pixel that cannot be modified, while 
the Os specify bits that can be altered. The plane mask can be altered with 
a call to the set_pmask function. See the TMS34010 User’s Guide for a fur¬ 
ther discussion of plane masking. 
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get_ppop Return Pixel Processing Operation 


Syntax int get_ppop() 

Type Core 

Description The get_ppop function returns the code forthe current pixel processing op¬ 
eration (the PROP field in the TMS34010’s Control register). The 5-bit 
PROP code resides in the 5 LSBs of the return value; all higher order bits 
are Os. 

The PROP code determines the manner in which pixels are combined (log¬ 
ically or arithmetically) during drawing operations. A new PROP code can 
be selected with the set_ppop function. Legal PROP codes are in the range 
0to21. 

Table 3-1. Pixel Processing Options 


Code 

Replace Destination Pixel with: 

Code 

Replace Destination Pixel with; 

0 

source 

11 

NOT source AND destination 

1 

source AND destination 

12 

all Is 

2 

source AND NOT destination 

13 

NOT source or destination 

3 

all Os 

14 

source NAND destination 

4 

source OR NOT destination 

15 

NOT source 

5 

source EQU destination 

16 

source + destination 

6 

NOT destination 

17 

ADDS (source, destination) 

7 

source NOR destination 

18 

destination - source 

8 

source OR destination 

19 

SUBS (destination - source) 

9 

destination 

20 

MAX (source, destination) 

10 

source XOR destination 

21 

MIN (source, destination) 


The effects of the 22 different codes are described in the TMS34010 User’s 
Guide. 

Example See call to set_ppop in drawjine. 


3-74 


TIGA Application Interface 




Return Text Rendering Attributes get_textattr 


Syntax int get_textattr(pControl, count, arg) 
char far ^pControl; 
short count; 
short far *arg; 

Type Extended 

Description The get_textattr function gets text rendering attributes, pcontroi is a 
control string specifying the attributes to be retrieved. Values associated 
with each requested attribute are stored in order in the array specified by 
arg. The number of attributes in the control string is passed in parameter 
count. The number of attributes successfully assigned is returned. This is 
the current list of valid attributes; 

Attribute Description _ Option Vaiue _ 

%a alignment 0 =topleft,1=baseline 

%e additional intercharacter spacing 16-bit signed integer 
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get_transp Return Transparency 


Syntax 

Type 

Description 


int get_transp 0 ; 

Core 

The get_transp function returns the state of the transparency enable bit 
(the T bit from the TMS340’s control register). A value of true (nonzero) is 
returned if transparency is enabled; otherwise, false (zero) is returned. 

Transparency is an attribute that affects text drawing and pattern fills. If 
transparency is enabled, and the result of a pixel processing operation is 0, 
the destination pixel is not altered. If transparency is disabled, the destina¬ 
tion pixel is replaced by the result of the pixel processing operation, regard¬ 
less of the value of that result. See TMS34010 User’s Guideior a further dis¬ 
cussion of transparency. 


3-76 


TiGA Application Interface 



Syntax 

Type 

Description 


Get Address at a TMS340 Trap Vector get_vect0r 


unsigned long get_vector(trapnum) 
unsigned short trapnum; 

Core 

The get_vector function returns the address currently in the trap vector 
specified by trapnum. This function should be used whenever it is neces¬ 
sary to read a trap vector address. 
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get_videoiTlode Return Current Emulation Mode 


Syntax 

Type 

Description 


int get_videomode(); 

Core 

The get_videomode function returns the current emulation mode. Possible 
emulation modes are discussed in the set videomode function. 


3-78 


TIGA Application Interface 



Syntax 

Type 

Description 


Return Windowing Mode get__wi ndowi ng 


int get_windowing 0 ; 

Core 

The get_windowing function returns the 2-bit windowing code contained 
in the control I/O register. The windowing codes are 

00 No windowing 

01 Interrupt request on write in window 

10 Interrupt request on write outside window 

11 Clip to window 

For a more detailed description of the windowing operation, refer to the 
TMS34010 User’s Guide. 
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get_Wksp Return Offscreen Workspace 


Syntax 

Type 

Description 

Exampie 


short get_wksp(addr,pitch) 

unsigned long *addr; pointer to workspace address */ 

unsigned long *pitch; /* pointer to workspace pitch */ 

Core 

The get_wksp function returns the parameters defining the current off¬ 
screen workspace. The function returns faise(zero) if no offscreen work¬ 
space is currentiy aliocated. True (nonzero) is returned if a valid offscreen 
workspace is present. If true is returned, then the address and pitch of the 
offscreen workspace is returned through the addr and pitch pointer pa¬ 
rameters, respectively. 

When using functions, such as fill_polygon, that require an offscreen work¬ 
space, check for a valid offscreen workspace by calling get_wksp. If none 
is present, then allocate one using gsp_malloc and update the workspace 
parameters via the set_wksp function. 

See fill_polygon. 
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Copy from GSP Memory to Coprocessor Memory gsp2cop 


Syntax 


Type 

Description 


void gsp2cop(copid,gspaddr,copaddr,length) 
short copid; 
long gspaddr; 
long copaddr; 
long length; 

Core 

The gsp2cop function copies data from TMS340 space into the coproces¬ 
sor space with ID copid (a number from 0 — 7, with 4 being broadcast, 
as defined in the TMS34020 User’s Guide). The size of the data to be 
transferred is in 32-bit long words. 
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9Sp2gsp Copy from GSP Memory to GSP Memory 


Syntax 

Type 

Description 


void gsp2gsp(addrl, addr2, length) 
long addrl; 
long addr2; 
long length; 

Core 

The gsp2gsp function copies length bytes from TMS340 memory to 
TMS340 memory. It handles overlapping regions. There is no restriction on 
the alignment of the address. 
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Move Data from GSP Memory to Host Memory gsp2hOSt 


Syntax void gsp2host(gptr, hptr, length, swizzle) 

long gptr; /* GSP memory pointer */ 

char far *hptr; /* host memory pointer */ 

unsigned short length ;/* length in bytes */ 

short swizzle; /* data SWIZZLE flag */ 

Type Core 


Description The gsp2host function copies length number of bytes from TMS340 
memory pointed to by gptr to host memory at hptr. If swizzle is nonzero, 
the data is swizzled before it is written to the host (that is, the order of the 
bits in each byte is reversed), gptr is a pointer to TMS340 memory. It must 
be byte-aligned (that is, 3 LSBs must be 0). hptr is a pointerto host memory. 
It must be declared as a long pointer (for example, segment:offset format). 
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gsp2hostxy Copy Rectangular Memory 


Syntax 


Type 

Description 


void gsp2hostxy(saddr, sptch, daddr, dptch, sx, sy, dx, dy, 
xext, yext, psize, swizzle) 

long saddr; 
long sptch; 
char far *daddr; 
long dptch; 
short sx; 
short sy; 
short dx; 
short dy; 
short xext; 
short yext; 
short psize; 
short swizzle; 

Core 


The gsp2hostxy function transfers a rectangular area from TMS340 to host 
memory. The area is extracted from the source bitmap starting at address 
saddr in TMS340 memory and is xext by yext pixels, with the pixel size 
being psize. The area starts at coordinates (sx, sy) in the source bitmap 
and is transferred to coordinates (dx, dy) of the destination bitmap. Be¬ 
cause the host memory address is restricted to be byte address aligned, the 
rectangular area sent is always padded on every side (if necessary) to en¬ 
sure that the data sent is aligned to the nearest byte boundary. The source 
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in the same column and adjacent rows of the bitmap in TMS340 memory, 
dpitch is the same for host memory. 


If swizzle is nonzero, the data is swizzled before it is written to the host 
(that is, the order of the bits in each byte is reversed). 


This function has three restrictions placed upon it: 

□ The source pitch (on the TMS340 side), though a long variable, must 
be less than 16 bits. 


Q All data in the host array must be accessible from the segment address 
of daddr ; that is, none of the data being transferred must have a host 
address that crosses segment boundaries. 

□ If data is being swizzled, it is transferred from TMS340 to host and then 
transferred back again. The integrity of the data is preserved only if it 
is transferred back to the same address it came from. Otherwise, the 
data may be garbled. 
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Syntax 

Type 

Description 


Clear and Allocate GSP Memory gsp_cal lOC 


long gsp_calloc(nmemb, size) 

long nmemb; /* number of items to allocate */ 

long size; /* size (in bytes) of each item */ 

Core 

The gsp_calloc function allocates a packet of TMS340 memory large 
enough to contain nmemb objects of the specified size and returns a pointer 
to it. If it cannot allocate the packet (that is, if it runs out of memory), it returns 
a null pointer (0). This function also initiates the allocated memory to all zer¬ 
os. This function is used in conjunction with gsp_free, gsp_malloc, 
gsp_minit, and gsp_realloc. 


3-85 



gsp_execute Execute a COFF Program 


Syntax 

Type 

Description 

Exampie 


void gsp_execute(entry_point) 
unsigned long entrY_point; 

Core 

The gsp_execute function is not of generai use to a TIGA application but 
is included here because the capability to load the graphics manager is an 
integral part of TIGA. As a side effect of this TIGA provides a portable COFF 
loader across all TMS340 boards. This function executes a program that 
has been loaded by the loadcoff function. The parameter entry_point 
specifies the start address of the program. On most TMS340 boards, this 
address loads into the NMI vector and an NMI is performed. 

#include <tiga.h> 

main(argc, argv) 
int argc; 
char *argv[]; 

{ 

unsigned long entry; 

if (argc == 2) 

{ 

if (cd_is_alive()) 

{ 

if (entry = loadcoff(argv[1])) 
gsp_execute(entry); 
else 

printf("Error in load\n"); 

} 

else printf("TIGACD not runningVn"); 

} 

else printf("Usage: load <coff filename>\n"); 

} 
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Syntax 

Type 

Description 

Exampie 


Free GSP Memory from Allocation gsp_f ree 


int gsp_free(ptr) 
long ptr; 

Core 

The gsp_free function routine deallocates a packet of TMS340 memory 
(pointed to by ptr) previously allocated by gsp_malloc, gsp_calloc, or 
gsp_realloc. The function takes no action and returns false (zero) when an 
attempt is made to free a packet not previously allocated. This function re¬ 
turns true (nonzero) if the function sucessfully frees a valid TMS340 pointer. 

See draw_ovalarc. 
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gsp_mallOC Allocate GSP Memory 


Syntax long gsp_malloc (size) 

long size; /* size (in bytes) of block */ 

Type Core 

Description The gsp_malloc function allocates a packet of TMS340 memory of a speci¬ 

fied size and returns a pointer to it. If gsp_malloc is unable to allocate the 
packet (that is, if it runs out of memory), it returns a null pointer (0). This func¬ 
tion does not modify the memory it allocates. This function is used in con¬ 
junction with gsp_free, gsp_minit, and gsp_realloc. 

Exampie See fill_polygon. 
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Return Largest Free Block gsp_maxheap 


Syntax long gsp_maxheap () 

Type Core 

Description The gsp_maxheap function returns the size of the largest contiguous 
block of program memory for heap allocation. It can be used at the start of 
an application to determine the total size of the available memory for heap 
allocation. If called during an application, it informs the application of the 
largest available block to download an object, for example, a bitmap. 
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gsp_minit Reinitialize Dynamic Memory Pool 


itWSSSSS 


Syntax 

Type 

Description 


void gsp_minit (stack_size) 
long stack size; 

Core 

The gsp_minit function reinitializes and frees ail pointers in the TMS340 
dynamic memory in the heap pool. Any previously allocated blocks are no 
longer allocated, and all pointers to such blocks become invalid after this 
procedure is called. It can also be used to modify the stack_size. The de¬ 
fault stack size is defined in the CONFIG structure. Supplying an argument 
of -1 selects this stack size. Select a larger/smaller stack by supplying the 
stack size in bits. 

Be carefui using this function because all allocated blocks of memory are 
freed, possibly including the background save area for the cursor (if stored 
in heap). Disable the cursor prior to calling this function and instaii a new cur¬ 
sor via a call to set_curs_shape afterward. If the workspace set by the 
set_wksp function was previously allocated in heap, it wiii have to be reset 
before using it. gsp_niinit aiso frees data associated with downloaded 
extensions and interrupt service routines. Therefore, any required 
extensions or interrupt handlers must be reloaded after calling gsp_minit. 
This function is used in conjunction with gsp_free, gsp_malloc, and 
gsp_realloc. 
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Reallocate GSP Memory gsp_real lOC 


Syntax long gsp_realloc(ptr, size) 

long ptr; /* pointer to object to change */ 

long size; /* new size (in bytes) of packet */ 

Type Core 

Description The gsp_realloc function changes the size of the allocated data area 
pointed to by the first argument, ptr, to the size specified by the second 
argument. It returns a pointer to the space allocated since the packet and 
its contents may have to be moved to expand. Any memory freed by this op¬ 
eration is deallocated. If an error occurs, the function returns a zero. This 
function is used in conjunction with gsp_calloc, gsp_free, gsp_malloc, 
and gsp_minit. 
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hOSt2gsp Move Data from Host Memory to GSP Memory^ 


Syntax void host2gsp(hptr, gptr, length, swizzle) 


char far *hptr 

/* 

host memory pointer 


long gptr; 

/* 

GSP memory pointer 

*/ 

unsigned short length 

/* 

length in bytes 

*/ 

short swizzle 

/* 

data SWIZZLE flag 



Type Core 

Description The host2gsp function copies length number of bytes from the host 
memory pointed to by hptr, to TMS340 memory at gptr. if swizzle is non¬ 
zero, the data is swizzled before it is written to the TMS340 (that is, the 
order of the bits in each byte is reversed), hpt r is a pointer to host memory 
and must be deciared as a iong pointer (that is, segment:offset format), gptr 
is a pointer to TMS340 memory. It must be byte aligned (that is, 3 LSBs must 
be 0). 

Exampie See get_offscreen_memory. 
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Copy Rectangular Area from Host to GSP hOSt2gspxy 


Syntax void host2gspxy(saddr, sptch, daddr, dpitch, sx, sy, dx, dy, 

xext, yext/ psize, swizzle) 
char far *saddr; 
long sptch; 
long daddr; 
long dptch; 
short sx; 
short sy; 
short dx; 
short dy; 
short xext; 
short yext; 
short psize; 
short swizzle; 

Type Core 

Description The host2gspxy function transfers a rectangular area from host to TMS340 
memory. The area is extracted from the source bitmap starting at address 
saddr in host memory and is xext by yext pixels, with the pixel size being 
psize. The area starts at coordinates (sx, sy) in the source bitmap and is 
transferred to coordinates (dx, dy) of the destination bitmap. Because the 
host memory address is restricted to be byte address aligned, the rectangu¬ 
lar area sent is always padded on every side (if necessary) to ensure that 
the data sent is aligned to the nearest byte boundary.The source pitch, 
spitch, is the difference in the linear addresses between two pixels in the 
same column and adjacent rows of the bitmap in host memory. The destina¬ 
tion pitch dpitch is the same for TMS340 memory. 

If swizzle is nonzero, the data is swizzled before it is written to the TMS340 
(that is, the order of the bits in each byte is reversed). 
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init__palet Default Palette 


Syntax 

Type 

Description 


Exampie 


void init_palet() 

Core 


The init_palet function initializes the first 16 entries of the palette to the 
EGA default colors: 


index 0 = Black 
index 1 = Blue 
index 2 = Green 
index 3 = Cyan 
index 4 = Red 
index 5 = Magenta 
index 6 = Brown 
index 7 = Light Gray 


index 8 = Dark Gray 
index 9 = Light Blue 
index 10 = Light Green 
index 11 = Light Cyan 
index 12 = Light Red 
index 13 = Light Magenta 
index 14 = Yellow 
index 15 = White 


The palette may well contain more than 16 entries. If so, this function repli¬ 
cates these 16 colors through the rest of the palette. 


See get_palet_entry. 
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Syntax 

Type 

Description 


Initialize Text Drawing Environment init_text 
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void init_text() 

Core 

The init_text function removes all installed fonts from the font table and se¬ 
lects the OEM system font for use in subsequent text operations. It also re¬ 
sets all text drawing attributes to their default state. 
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install aim install Absolute Load Module 


Syntax 

Type 

Description 


Example 


int install_alm (alm_name) 

char far *alm__name; /* load module filename */ 

Core 

The install_alm function installs the absolute load module (specified by the 
function aim_name) into theTIGA graphics manager and returns a module 
identifier which is used to invoke the extensions specified in the TIGAEXT 
section. 

If the module contains interrupt service routines, they will be installed into 
TIGA, and the priority information associated with each can be retrieved 
once instaliation is complete, with a call to getJsr_prloritles, which returns 
a priority list for last block of ISRs installed. For more details on extensibility 
and the use of this function, refer to Chapter 4. 

If an error occurs, a negative error code number is returned. Othenwise a 
module identifier is returned. This module identifier should be used whenev¬ 
er a routine contained within this module is specified, by joining the identifier 
with the routine number and command type using the bitwise-OR operator 
(I). 

These are the error codes returned by this function: 

Error Description 

Code 

-1 System Error - Could not find tigalnk in main TIGA directory: 
either the TIGA environment variable -m option is not set, or that 
directory does not contain tigalnk . exe. 

-3 Out of Memory - Not enough host memory to run tigalnk or not 

enough TMS340 memory to store ALM. 

-4 Communications Driver not Running - Run tigacd 

-5 Graphics Manager not Running - Run tigalnk -ix 

-8 Missing ALM - Either the spelling of the ALM filename does not 
match the ALM filename in the current directory, or the -i option of 
the TIGA environment variable is not set up. 

See Section 4.3.2 on page 4-8. 
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Install Font in Table install font 


Syntax short install_font(pFont) 

unsigned long pFont; 

Type Extended 

Description The install_font function installs the font pointed to by pFont into the font 
table and returns an identifier (ID) for the font that can be used to reference 
the font in subsequent text operations. 

Note that pFont is a pointer to a font already located in TMS340 memory. 
The install_font function merely adds the address of the font to the font 
table. The font must first be loaded from disk by the host and downloaded 
intoTMS340 memory. This is shown in the example. 

The ID returned is nonzero if the installation was successful. If unsuccesful, 
the reserved ID for the system font (zero) is returned. For further details on 
the font format see Appendix A. 
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install font install Font in Table 


/ 


Example #include <tiga.h> 

#include <typedefs.h> 

#include <extend.h> 

#include <stdio.h> 

#include <malloc.h> 

#define FONT_MAGIC 0x8040 
typedef struct 
{ 

ushort magic; 
long size; 

} FILEHDR; 

/*LOADINST_FONT() Load, install font and return ref. ID */ 
int loadinst_font(name) 
char "^name; 

{ 

FILE *fp; 

FILEHDR fh; 

FONT *hpTmp; 
int id = 0; 

PTR gpTmp; 

/* Examine font hdr. magic num. If incorrect return 0. */ 

if (!(fp = fopen( name, "rb"))) return (0); 
fread( &fh, sizeof(FILEHDR), 1, fp) ; 
if (fh.magic != FONT_MAGIC) 

{ 

fclose(fp); 
return (0); 

} 

Malloc font in host and target. Read font into host, 

/'^ then move to target and free host memory. 
if (hpTmp = (FONT*)malloc((ushort)fh.size)) 
if (gpTmp = (PTR)gsp_malloc( fh.size)) 

{ 

rewind(fp); 

fread( hpTmp, fh.size, 1, fp); 
host2gsp (hpTmp, gpTmp, fh.size, 0); 
free( hpTmp); 

} 

/* If all is OK, then install the font. */ 

if (gpTmp) 

id = install_font(gpTmp); 
fclose(fp); 
return (id); 
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Install Extended Drawing Primitives installjprimitives 


Syntax int install_primitives o 

Type Core 

Description The install_primitives function is similarto a call to install_rlm and is used 
to download extended primitives such as drawjine etc. Before calling an 
extended primitive download them either by this command, or by installing 
a dynamic load module, that includes the primitives. For more details on ex¬ 
tensibility and the use of this function, refer to Chapter 4. 

If the extended primitives are currently installed when install_primitives is 
called, no action is performed. 

This function returns these error codes; 

Error Description 

Code 

-1 System Error - Could not find tigalnk in main TIGA directory, 
either the TIGA environment variable -m option is not set, or that 
directory does not contain tigalnk.exe. 

-3 Out of Memory - Not enough host memory to run tigalnk or not 
enough TMS340 memory to store RLM. 

-4 Communications Driver not Running - Run tigacd. 

-5 Graphics Manager not Running - Run tigalnk -ix 

-7 Symbol File Error - I/O error obtained in accessing symbol file. 
The -m option of the TIGA environment variable is not set or the 
directory does not contain tiga340 . sym, orthefile is corrupt. Inthe 
latter case, recopy this file from your backup disk. 

-10 Symbol Reference- An unresolved symbol was referenced by the 
RLM. Determine the name either by producing a link map for the 
RLM or by invoking tigalnk from the command line. 

-12 Symbol Table Mismatch - The modules installed in the symbol 
table do not match those the TIGA graphics manager has installed. 
Reinitialize the modules by a call to flush_extended and install 
them again. 
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install_prinriitives install Extended Drawing Primitives 


Example #include <typedefs.h> 

#include <tiga.h> 

#include <extend.h> 

CONFIG config; 

main() 

{ 

/* using INIT_GLOBALS does not initialize the heap, */ 

/* if the primitives were installed they still are */ 

if (set__videomode(TIGA, INIT_GLOBALS | CLR_SCREEN)) 

{ 

/* install the optional TIGA extended primitives */ 

if (install_primitives0 < 0) 

{ 

printf("Cannot install extended primitivesXn"); 
exit (0); 

} 

get__conf ig (sconfig) ; 
set_f color (LIGHT_GRAY) ; 

draw_line(0, 0, config.mode.disp_hres, 
config.mode.disp__vres) ; 
set_videomode(PREVIOUS, INIT); 

} 

} 
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Install Relocatable Load Module install rim 


Syntax int install_rlm(rlin_name) 

char far *rlm_name; /* load module filename */ 

Type Core 

Description The install_rlm function installs the relocatable load module (specified by 
rim_name) Into TIGA and retums a module identifier that is used to invoke 
the extensions specified in the TIGAEXT section. 

If the module contains interrupt service routines, they are installed into the 
TIGA graphics manager. The priority information associated with each can 
be retrieved once installation is complete with a call to the function 
getJsr_prlorlties which returns a priority list for the last block of ISRs in¬ 
stalled. 

If an error occurs, a negative module number is returned. Othenwise a mod¬ 
ule identifier is returned. This module identifier should be used whenever 
a routine contained within this module is specified, by joining the identifier 
with the routine number and command type using the bitwise-OR operator 

(I). 

For more details on extensibility and the use of this function refer to Chapter 
4. 

This function returns these error codes: 

Error Description 

Code 

-1 System Error - Could not find tigalnk in main TIGA directory, 
either the TIGA environment variable -m option is not set or that 
directory does not contain tigalnk.exe. 

-3 Out of Memory - Not enough host memory to run tigalnk or not 
enough TMS340 memory to store RLM. 

-4 Communications Driver not Running - Run tigacd. 

-5 Graphics Manager not Running - Run tigalnk -ix 

-6 Missing RLM - Either the spelling of the RLM filename does not 
match the RLM filename in the current directory or the -i option of 
the TIGA environment variable is not set up. 

-7 Symbol File Error - I/O error obtained in accessing symbol file. 
The -m option of the TIGA environment variable is not set or the 
directory does not contain tiga340 . sym or the file is corrupt. In the 
latter case, recopy this file from your backup disk. 

-1 0 Symbol Reference - An unresolved symbol was referenced by the 

RLM. Determine the name either by producing a link map for the 
RLM or by invoking tigalnk from the command line. 
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install rim install Relocatable Load Module 


Error Description (continued) 

Code 

-12 Symbol Table Mis-match - The modules installed in the symbol 
table do not match those the TIGA graphics manager has installed. 
Reinitialize the modules by a call to flush_extended and Install 
them again. 

Example See Section 4.3.1 on page 4-7. 
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Install User Error Handler install USererror 


Syntax void install_usererror(function_name) 

void (far *function_name) (); 

Type Core 

Description The install_usererror function installs a user error function that is called 
when an error is found in the host communications. The default usererror 
function simply prints a message to the screen when an error occurs. The 
user can install another function to trap these errors and handle them ac¬ 
cordingly. The user error function expects the following parameters: 

usererror (command__number, error_code) 
unsigned short command_nuinber; 
short error_code; 

Current error codes: 

1 Timeout with TMS340 communication on trying to load new func¬ 
tion; that is, a previous function has not completed. 

2 Timeout on waiting for TMS340 function to complete; that is, the 
function just invoked has not completed. 

3 Parameter allocation failure, not enough memory to allocate a buff¬ 
er to download data from the current function. 

Exampie #include <typedefs.h> 

#include <tiga.h> 

#include <extend.h> 

CONFIG config; 

#define nofpts 4000 
short lotofpts[nofpts*2]; 

far usererror (command_nuiriber, error__code) 
unsigned short command_number/ 
short error_code/ 

{ 

printf("TIGA error code of %d in command number %4x\n", 
error_code, command_number); 

} 
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install usererror install User Error Handier 


main() 

{ 

int i, X, y; 

if (set_videomode(TIGA, INIT | CLR_SCREEN)) 

{ 

if (install_primitives() >= 0) 

{ 

get_config(Sconfig); 
install___usererror (usererror) / 

/* initialize nofpts points to some value */ 

X = y = 0; 

for (i = 0; i < nofpts*2; ) 

{ 

lotofpts[i++] = x; 
lotofpts[i++] = y; 
if (i % 4) 

{ 

if (x++ > config.mode.disp_hres) 

X = 0; 

} 

else 

{ 

if (y++ > config.mode.disp_vres) 
y = 0; 

} 

} 

/* set timeout value to 1 second */ 

set_timeout(1000); 
set_pensize(64,64); 

/* tie up the GSP to get timeout since many points '^/ 
/* are being downloaded, use parameter alloc entry */ 
/* points to allocate a temporary command buffer 
/* for the data transfer from host to GSP */ 

pen_polyline_a(nofpts, lotofpts); 

/* wait for GSP side to finish (to producetimeouts) */ 
synchronize 0; 

} 

set_videomode(PREVIOUS, INIT); 

} 

} 
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Leftmost One Imo 


Syntax 

Type 

Description 

Exampie 


int Imo(n) 

long n; /* 32-bit integer */ 

Core 

The Imo function calculates the bit number of the leftmost one in argument 
n. The argument is treated as a 32-bit number whose bits are numbered 
from 0 to 31, where bit 0 is the LSB (the rightmost bit position) and bit 31 
is the MSB (the leftmost bit position). 

For nonzero arguments, the return value is in the range 0 to 31. If the argu¬ 
ment is 0, a value of -1 is returned. 

See fill_polygon. 


3-105 



loadCOff Load COFF File 


Syntax 

Type 

Description 


Exampie 


unsigned long loadcoff(filename) 
char far ^filename; 

Core 

The loadcoff function is not of general use to a TIGA application but is 
included here because the capability to load the graphics manager is an 
integral part of TIGA. With this function TIGA provides a portable COFF 
loader across all TMS340 boards. This function loads the COFF file 
specified in the parameter. It returns false (zero) if an error occurs during 
the load; otherwise, it returns the entry point address of the program.The 
entry point can be passed to the gsp_execute function to execute the 
COFF file. 

See gsp_execute. 


3-106 


TIGA Application Interface 



Return Status of Page Flipping page_busy 


Syntax 

Type 

Description 

Example 


short page_busy() 

Core 

The page_busy function is used in conjuction with the page_fiip function 
to determine the status of page flipping. page_busy returns true (nonzero) 
if page_flip is called and the pages have not been flipped. Otherwise, false 
(zero) is returned. 

See pagejiip. 
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page_flip Set Display and Drawing Pages 


Syntax 

Type 

Description 


int page_flip(display, drawing) 
short display; 
short drawing; 

Core 

The page_flip function can be used if the num_pages entry in the CONFiG 
structure (described in Appendix A) is greater than 1, indicating that muitiple 
frame buffers are avaiiable in a particular configuration. This function sets 
the display page to display a particular frame buffer and sets the drawing 
page for subsequent drawing operations. 

The switching of display and drawing pages is performed at the start of verti¬ 
cal blanking. 

If the function completes normally, it returns true (nonzero). If the display or 
drawing page is invalid, the function aborts and returns false (zero). 
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Set Display and Drawing Pages page__f I i p 

Example #include <stdio.h> 

tinclude <typedefs.h> 

#include <tiga.h> 

#include <extend.h> 

#define TRUE 1 
#define BALL_WT 16 
#define BALL_HT 16 
#define XMIN 0 
#define YMIN 0 

#define XMAX (config.mode.disp_hres-BALL_WT) 

#define YMAX (config.mode.disp_vres-BALL_HT) 

#define NUM_SPRITES 15 

typedef struct 

{ 

short x; 
short y; 

} SPRITE; 

CONFIG config; 

MODEINFO modeinfo; 

short display_page =0; 
static SPRITE sprite[NUM_SPRITES]; 
static short dx[NUM_SPRITES]; 
static short dy[NUM_SPRITES]; 

flip_page() 

{ 

display_page 1; 

page_f lip (display__page, l-display_page) ; 

} 

init___logic () 

{ 

register int i; 
srand(9); 

for (i =0; i < sizeof(sprite)/sizeof(SPRITE); i++) 

{ 

sprite[i].x = rand() % (config.mode.disp_hres - 32); 

sprite[i].y = rand() % (config.mode.disp__vres - 32); 

dx[i] = (randO % 6) + 1; 

dy[i] = (randO % 5) + 1; 

} 

} 
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build_screen() 

{ 

register int i; 

set_fcolor(0); 
clear_page(BLACK); 

for (i = 0;i < sizeof(sprite)/sizeof(SPRITE);i++) 

{ 

set_f color(i+1); 

fill_oval(16,16,sprite[i].x,sprite[i].y)/ 

} 


animate() 

{ 

register int i; 

short tx, ty, tdx, tdy; 

for (i =0; i < sizeof(sprite)/sizeof(SPRITE); i++) 

{ 

tx = sprite[i].x; 
ty = sprite[i].y; 
tdx = dx[i]; 
tdy = dy[i]; 

if (tx >= XMAX && tdx > 0) tdx = -tdx; 
else if (tx <= XHIN StSc tdx < 0) tdx = -tdx; 

else if (ty >= YMAX && tdy > 0) tdy = -tdy; 

else if (ty <= YMIN && dy[i] < 0) tdy = -tdy; 

sprite[i].x += ( dx[i] = tdx ); 

sprite[i].y += ( dy[i] = tdy ); 

} 

while (page_busy()); 
build_screen(); 
flip_page(); 
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main() 

{ 

int mode, oldmode; 

if (set_videomode(TIGA, INIT | CLR_SCREEN)) 

{ 

if (install__primitives () >= 0) 

{ 

get_config(&config); 
oldmode = config.current_mode; 

/* look for a mode with more than 1 display page */ 
mode =0; 

do get_modeinfo(mode, Smodeinfo); 
while {(modeinfo.num_pages == 1) && 

(++mode < config.num_modes)); 
if (modeinfo.num_pages > 1) 

{ 

/* set configuration to multiple pages mode 
set_conf ig (mode, TRUE); 

/* update config structure for current mode '^/ 

get_conf ig (Sconf ig) ; 

flip_page(); 

init_logic () ; 

do animate 0; 

while (IkbhitO); 

getch 0; 

} 

if (mode != oldmode) 

{ 

/* restore old mode */ 

set_config(oldmode, TRUE); 
clear_frame_buffer(BLACK); 

} 

} 

set__videomode (PREVIOUS, INIT) ; 

} 

} 
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Syntax typedef struct 

{ 

short x; 
short y; 

}POINTS; 

void patnfill_convex(n, points); 
short n; 

POINTS far ^points; 

Type Extended 

Description The patnfiil_convex function fills a convex polygon with a pattern, given 
a list of points representing the vertices. To be drawn correctly, the polygon 
must be convex; that is, it should contain no concavities. A polygon must 
have at least three vertices to be visible. To ensure that the polygon is 
closed, the first and last vertices should contain the same coordinates. The 
polygon is pattern-filled with the current pattern, which is drawn in the cur¬ 
rent foreground and background colors. 

The function requires two input arguments: 

□ The first argument, n, defines the number of vertices in the polygon. 

□ The second argument, points, is an array in which each pair of adja¬ 
cent 16-bit quantities contains the X and Y coordinates, respectively, of 
a vertex. 

The patnfill_convex function automatically culls back faces to support 3D 
applications. A polygon is drawn only if its front side is visible, that is, if it is 
facing toward the screen. If the vertices are specified in counterclockwise 
order, the polygon is assumed to be facing away from the screen and is 
therefore not drawn. 

The back face test is done by first comparing vertices n - 2, n -1, and 0 to 
determine whether the polygon vertices are specified in clockwise (front 
face) or counterclockwise (back face) order. This test relies on the polygon 
containing no concavities. If the three vertices are colinear, the back face 
test is made again using the next three vertices, n -1,0, and 1. The test re¬ 
peats until three vertices are not colinear. If all the vertices are colinear, the 
polygon is invisible. 

This function is similar to the patnfill_polygon function but is specialized 
for rapid drawing of convex polygons. 

The argument point s can be of any length. The application can easily over¬ 
flow the command buffer which is used by the host processor to send the 
function parameters to the TMS340. The size of the command buffer is in 
the CONFIG structure (described in Appendix A) returned by the get_con- 
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fig function. It is up to the application to check that the data sent wiil not over¬ 
flow this buffer. 

The number of points that can be sent is given by the following formula: 

com_buffer_size (in bytes) -10 

n < - 

4 

An alternate entry point patnfill_convex_a with the same parameterization 
is also supplied to check the size of the data to be sent. If the command buff¬ 
er overflows patnfill_convex_a will attempt to allocate a temporary buffer 
in heap. In this way, the application is freed from having to check the size 
of the data being transferred: however, the invocation of the function takes 
longer becuase the length of the data must be parsed. If there is not enough 
room to store the temporary buffer in TMS340 memory, the error function 
is invoked (which can be trapped by the install_usererror function). 
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Syntax 

Type 

Description 

Exampie 


void patnfill_oval(w, h, xleft, ytop) 

short w, h; /* width, height of enclosing rect. */ 

short xleft, ytop;/* XY coordinates of top left corner */ 

Extended 

The patnfill_oval function fills an ellipse with the current pattern in the cur¬ 
rent foreground and background colors. The ellipse is in standard position, 
with its major and minor axes parallel to the coordinate axes. 

The ellipse is defined by the minimum enclosing rectangle in which it is in¬ 
scribed. Four arguments define the rectangle: 

□ The width w 

□ The height h 

Q The coordinates of the top left corner (xieft, ytop) 

See similar call to patnfili_piearc. 
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Syntax void patnfill_piearc(w, h, xleft, ytop, theta, arc) 


short 

w, h; 

/* 

width and height 


short 

xleft, ytop; 

/* 

top left corner 

*/ 

short 

theta; 

/* 

starting angle (degrees) 


short 

arc; 

/* 

extent of angle (degrees) 



Type Extended 

Description The patnfill_piearc function fills a pie-shaped wedge with a pattern. The 
wedge is bounded by an arc and two straight edges. The arc is taken from 
an ellipse in standard position, with its major and minor axes parallel to the 
coordinate axes. The two straight edges are defined by lines connecting the 
end points of the arc with the center of the ellipse. The arc is filled with the 
current pattern in the current foreground and background colors. 

The ellipse from which the arc is taken is specified in terms of the minimum 
enclosing rectangle in which it is inscribed. The first four arguments define 
the rectangle: 

□ The width w 

□ The height h 

□ The coordinates of the top left corner (xief t, ytop) 

The last two arguments define the limits of the arc: 

□ The starting angle, theta, is measured from the center of the right side 
of the enclosing rectangle and is treated as modulus 360. Positive 
angles are measured clockwise; negative angles are measured coun¬ 
terclockwise. 

□ The arc extent, arc, specifies the number of degrees (positive or nega¬ 
tive) spanned by the angle. If the arc extent is outside the range 
[-359,+359], the entire ellipse is drawn. 

Both arguments are expressed in degrees of elliptical arc, with 360 degrees 
representing one full rotation. 
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Example finclude <typedefs.h> 
#include <tiga.h> 
#include <extend.h> 


CONFIG config; 


/* number of installed patterns 

#define PMAX 9 

typedef short PAT_ARY[16]; 

PAT_ARY patterns[PMAX] - 

{ 

/* PATTERN # 0 

{ 0x0000, 0x3FFC, OxVFFE, 0x0006, 0x0006, 0xlFC6, 0x3FE6,0x3066, 

0x3066, 0x33E6, 0x31C6, 0x3006, 0x3006, 0x3FFE, OxlFFC, 0x0000}, 

/* PATTERN # 1 

{0x0000, 0x0080, 0x0080, 0x0080, OxOlCO, OxOlCO, 0x7FFF, OxlFFC, 

0x0FF8, 0x03E0, 0x03E0, 0x07F0, 0x0630, OxOC18, 0x0808, 0x0000}, 

/* PATTERN # 2 

{ 0x0000, 0x0000, 0x0E38, 0xlF7C, 0x3FFE, 0x3FFE, OxSFFE, 0x3FFE, 

OxlFFC, 0x0FF8, 0x07F0, 0x03E0, OxOlCO, 0x0080, 0x0000, 0x0000 }, 

/* PATTERN # 3 

{ 0x0000, OxOlCO, 0xl9CC, 0xl88C, 0x0490, 0x02A0, 0x31C6, 0x3FFE, 

0x31C6, 0x02A0, 0x0490, 0xl88C, 0xl9CC, OxOlCO, 0x0000, 0x0000 }, 

/* PATTERN # 4 

{ 0x0420, 0x0420, 0x3FFC, 0x2424, 0x2424, 0xFC3F, 0x2004, 0x2004, 

0x2004, 0x2004, 0xFC3F, 0x2424, 0x2424, 0x3FFC, 0x0420, 0x0420 }, 

/* PATTERN # 5 

{ 0x0101, 0x0101, 0x8282, 0x7C7C, 0x1010, 0x1010, 0x2828, 0xC7C7, 

0x0101, 0x0101, 0x8282, 0x7C7C, 0x1010, 0x1010, 0x2828, 0xC7C7 }, 

/yc pattern # 6 

{ 0x0000, 0x0000, 0x0000, OxlFFO, OxlFFO, OxOABO, 0x1570, OxOABO, 

0x1570, OxOABO, 0x1570, OxOABO, 0x0000, 0x0000, 0x0000, 0x0000 }, 

/* PATTERN # 7 

{ 0x0000, 0xFE7F, 0xFE7F, 0xFE7F, 0xFE7F, 0xFE7F, 0xFE7F, 0x0000, 

0x0000, 0x7FFE, 0x7FFE, 0x7FFE, 0x7FFE, 0x7FFE, 0x7FFE, 0x0000 }, 

/* PATTERN # 8 

{ 0xF007, 0xF803, 0x9C03, 0x0E07, 0x070E, 0x039C, 0x03F8, 0x07F0, 

OxOFEO, OxlFCO, 0x39C0, 0x70E0, 0xE070, 0xC039, OxCOlF, OxEOOF }, 

}; 

static short angles[] ={33, 22, 50, 16, 24, 60, 75, 55, 
/* Initialize pattern structure 
PATTERN patn = 

{ 

16,16,1,0L /* width, height, depth, data ptr 

}/ 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

58}; 
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main() 

{ 

short w, h, X, y, theta, arc, i; 

PTR gsp_patterns; 

if (set_videomode(TIGA, INIT | CLR_SCREEN)) 

{ 

if (install__primitives () >= 0) 

{ 

get_config(&config); 

/* allocate space for patterns in GSP memory */ 

gsp_j)atterns = gsp_malloc(PMAX * sizeof(PAT_ARY)); 

/* download patterns from host to gsp */ 

host2gsp ((char far *) patterns, gsp_patterns, 

PMAX * sizeof(PAT_ARY), 0); 

/* setup up with rectangle for the piechart */ 

w = conf ig .mode. disp_hres»l; 
h = conf ig. mode. disp_vres»l; 

X = conf ig. mode. disp_hres»2; 
y = conf ig .mode. disp_hres»2; 
set_bcolor (BROWN) ; 
set_f color (GREEN) ; 
theta = angles[0]; 

/* draw a piechart with pies filled with patterns */ 
for (i = 1; i < 9; ++i) 

{ 

arc = angles [i]; 

patn.data = gsp_patterns + ((long)i«8); 
set__patn ( (char far*) &patn) ; 
patnfill_piearc (w, h, x, y, theta, arc); 
theta += arc; 

} 

set_fcolor(CYAN); 
frame_oval(w, h, x, y, 2, 2); 

} 

set_videomode(PREVIOUS, INIT); 

} 

} 
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Syntax typedef struct 

{ 

short x; 
short y; 

IPOINTS; 

void patnfill_polygon(n, points) 
long n; 

POINTS far ^points; 

Type Extended 

Description The patnfill_polygon function fills a polygon with a pattern, given a list of 
endpoints of the polygon. No restrictions are placed on the shape of the 
polygons filled by this function: edges can cross each other, filled areas 
can contain holes, and two or more filled regions can be disconnected 
from each other. The polygon is filled with the current pattern using the 
current foreground and background colors. To ensure that the polygon is 
closed, the first and last vertices should have the same coordinates. 

The function requires two input arguments: 

□ The first argument, n, defines the number of vertices in the polygon. 

□ The second argument, points, is an array in which each pair of adja¬ 
cent 16-bit quantities contains the X and Y coordinates, respectively, of 
a vertex. 

This function also takes as an implied argument a 1 -bit representation of the 
frame buffer, which it uses as a temporary workspace. This workspace must 
be set up prior to invoking the patnfill_polygon function (via a call to the 
set_wksp function). 

The argument points can be of any length. The application can easily 
overflow the command buffer that is used by the host processor to send the 
function parameters to the TMS340. The size of the command buffer is in 
the CONFIG structure (described in Appendix A) returned by the get_con- 
figfunction.lt is up to the application to check that the data sent will not over¬ 
flow this buffer. 

The number of points that can be sent is given by the following formula: 
com_buffer_size (in bytes) -10 


An alternate entry point, patnfill_polygon_a with the same parameteriza¬ 
tion, is also supplied to check the size of the data to be sent. If the command 
buffer overflows, patnfill_polygon_a attempts to allocate a temporary buff¬ 
er in heap. In this way, the application is freed from having to check the size 
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of the data being transferred. There is a cost, however, in that the invocation 
of the function takes longer since the length of the data has to be parsed. 
If there is not enough room to store the temporary buffer in TMS340 
memory, the error function is invoked (which can be trapped by the In- 
stall_usererror function) 

Example See call to filI_polygon. 
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Syntax 

Type 

Description 

Exampie 


void patnfill_rect(w, h, xleft, ytop) 

short w, h; /* width and height of rectangle */ 

short xleft, ytop; /* XY coord at top left corner */ 

Extended 

The patnfili_rect function fills a rectangle with the current pattern in the cur¬ 
rent foreground and background colors. Four arguments define the rectan¬ 
gle: 

Q The width w 

□ The height h 

□ The coordinates of the top left corner (xief t, ytop) 

See call to fill_rect in fill_polygon example. 
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Syntax void patnf rame_oval (w, 

short w, h; 
short xleft, ytop; 
short dx, dy; 

Type Extended 


h, xleft, ytop, dx, dy) 

/* width, height of rect. */ 
/* coordinates at top left corner */ 
/* width, height of frame border */ 


Description The patnframe_oval function fills an ellipse-shaped frame with a pattern. 

The frame consists of a filled region between two concentric ellipses. The 
frame is filled with the current pattern in the current foreground and back¬ 
ground colors. The portion of the screen enclosed by the frame is not al¬ 
tered. 


The outer ellipse is specified in terms of the minimum enclosing rectangle 
in which it is inscribed. The first four arguments define the rectangle: 

□ The width w 

□ The height h 

□ The coordinates of the top left corner (xieft, ytop) 

The thickness of the frame in the X and Y dimensions is defined by two addi¬ 
tional arguments: 

□ dx specifies the horizontal distance between the outer and inner el¬ 
lipses. 

□ dy specifies the vertical distance between the outer and inner ellipses. 
Exampie See similar call to frame_oval in patnfill_piearc example. 
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Syntax void patnframe_rect(w, h, xleft, ytop, dx, dy) 

short w, h; /* width, height of rect. */ 

short xleft, ytop; /* coordinates at top left corner */ 

short dx, dy; /* width, height of frame border */ 

Type Extended 

Description The patnframe_rect function fills a rectangular frame with a pattern. The 
frame consists of a filied region between two concentric rectangies. The 
frame is filled with the current pattern in the current foreground and back¬ 
ground colors. The portion of the screen enciosed by inner edge of the frame 
is not altered. 

The first four arguments define the outer rectangle: 

□ The width w 

□ The height h 

Q The coordinates of the top ieft corner (xleft, ytop) 

The thickness of the frame in the X and Y dimensions is defined by two addi- 
tionai arguments: 

□ dx specifies the horizontai distance between the outer and inner rect¬ 
angies. 

□ dy specifies the vertical distance between the outer and inner rectan¬ 
gies. 
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ftsaxasmiwsiwsssssssssssssmsftwsftwmsssssss;:^^ 


Syntax 

void patnpen_line(xl. 

yl, x2, y2) 


short 

xl, yl; 


starting coordinates 


short 

x2, y2 

/* 

ending coordinates 

Type 

Extended 





Description The patnpenjine function uses the pen to draw a patterned line. Argu¬ 
ments xi and yi specify the starting coordinates of the line, and x 2 and y2 
specify the ending coordinates. 

The pen is a rectangle whose width and height can be modified by means 
of the set_pensize function. At each point on the line drawn by the patn¬ 
penjine function, the pen is located with its top left corner touching the line. 
The area covered by the pen is filled with the current pattern in the current 
foreground and background colors. 
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Example #include <typedefs.h> 
finclude <tiga.h> 
finclude <extend.h> 

CONFIG config; 


/* number of installed patterns */ 

#define PMAX 8 

typedef short PAT_ARY[16]; 

PAT_ARY patterns[PMAX] = 

{ 

/* PATTERN # 0 

{ OxAAFA, 0xFF77, OxFFFF, 0xFF77, OxAAFA, 0x7070, 0xF8F8, 0x7070, 

OxFAAA, 0x77FF, OxFFFF, 0x77FF, OxFAAA, 0x7070, 0xF8F8, 0x7070 }, 

/yc pattern # 1 

{ OxOOCO, 0x0030, 0xlF88, 0x2044, 0x4024, 0x4E24, 0x9124, 0xAlC4, 

0x2385, 0x2489, 0x2472, 0x2402, 0x2204, 0xllF8, OxOCOO, 0x0300 }, 

/yr pattern # 2 

{ 0x93C9, 0x0E70, 0xlC38, 0xB99D, 0xF24F, 0x6666, 0xCDB3, 0x4DB2, 

0x4DB2, 0xCDB3, 0x6666, 0xF24F, 0xB99D, 0xlC38, 0x0E70, 0x93C9 }, 

/* PATTERN # 3 

{ 0x0000, 0x7FFE, 0x6426, 0x524A, 0x4992, 0x6666, 0x566A, 0x4992, 

0x4992, 0x566A, 0x6666, 0x4992, 0x524A, 0x6426, 0x7FFE, 0x0000 }, 

/yr pattern # 4 

{ 0x0441, 0x8AA2, 0x5114, 0x2388, 0x5114, 0x8442, OxOEEl, 0xA54A, 

Qx739C, QXA.54A, QxOEEl, 0x8442, 0x5114, 0x2388, 0x5114, 0x8AA2 }, 

/* PATTERN # 5 

{ 0x0000, 0x601E, 0x7C31, 0x2733, 0x29B3, 0x34B0, 0xl2B0, 0xl8B0, 


0x0F70, 0x00B2, 0xlFF4, 

0x7FFC, 

0x601C, 

0x403C, 

0x5842, 0x3800 }, 

/yr pattern # 6 





{ 0x1111, 0x2222, 0x4444 

, 0x8888 

, 0x1111 

, 0x2222 

, 0x4444, 0x8888, 

0x1111, 0x2222, 0x4444, 

0x8888, 

0x1111, 

0x2222, 

0x4444, 0x8888 } 

/yr pattern # 7 





{ 0x8888, 0x4444, 0x2222 

, 0x1111 

, 0x8888 

, 0x4444 

, 0x2222, 0x1111 

0x8888, 0x4444, 0x2222, 

0x1111, 

0x8888, 

0x4444, 

0x2222, 0x1111 } 


}; 

/* Initialize pattern structure 
PATTERN pattern = 

{ 

16/16,1/OL /* width, height, depth, data ptr 

}; 


*/ 

*/ 

*/ 

*/ 

*/ 

yc/ 

*/ 
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main() 

{ 

long y; 

long r, t; 

short fcolor, colormax, patn; 

PTR gsp_patterns; 

if (set_videomode(TIGA, INIT 1 CLR_SCREEN)) 

{ 

if (install_primitives() >= 0) 

{ 

get_config(&config); 

set_draw_origin (config.mode. disp_hres»l, 
con fig. mode. disp_vres»l) ; 
set_pensize(4, 3) ; 

/* allocate space for patterns in GSP memory */ 

gsp_patterns = gsp_malloc(PMAX * sizeof(PAT_ARY)); 

/* download patterns from host to gsp */ 

host2gsp ((char far *) patterns, gsp_patterns, 

PMAX * sizeof(PAT_ARY), 0); 

/* initialize colormax variable */ 

colormax = (l«config.mode.disp_psize) - 1; 
fcolor =1; 
patn = 0; 

/* draw a swirling patterned shape */ 

for (r = 20; r < (config.mode.disp_vres»l) ; 
r += r » 4) 

{ 

X = 0; 

y = -r « 16; 

for (t = 0; t < 201; ++t) 

{ 

set_fcolor(fcolor); 

if (++fcolor == colormax) fcolor = 1; 
if (++patn == PMAX) patn =0; 
pattern.data = gsp_patterns+( (long)patn«8) ; 
set_patn(Spattern); 

patnpen_line (x~ (x»2) »16, y-(y»2)»16, x»16, 
y»16) ; 

X -= y » 5; 
y += X » 5; 

} 

} 

} 

set_videomode(PREVIOUS, INIT); 

} 

} 
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Syntax 


Type 

Description 


Example 


void patnpen_ovalarc(w, h, xleft, ytop, theta, arc) 


short 

w, h; 

/* 

width and height 


short 

xleft, ytop; 

/* 

top left corner 


short 

theta; 

/* 

starting angle (degree) 


short 

arc; 

/* 

angle extent (degrees) 



Extended 

The patnpen_ovalarc function uses the pen to draw a patterned arc of an 
ellipse. The ellipse is in standard position, with the major and minor axes 
parallel to the coordinate axes. 

The pen is a rectangle whose width and height can be modified by means 
of the set_pensize function. At each point on the arc drawn by the patn- 
pen_ovalarc function, the pen is positioned so that its top left corner 
touches the arc. The area covered by the pen is filled with the current pattern 
in the current foreground and background colors. 

The ellipse from which the arc is taken is specified in terms of the minimum 
enclosing rectangle in which it is inscribed. The first four arguments define 
the rectangle: 

□ The width w 

□ The height h 

□ The coordinates of the top left corner (xief t, ytop) 

The last two arguments define the limits of the arc: 

□ The starting angle, theta, is measured from the center of the right side 
of the enclosing rectangle, and is treated as modulus 360. Positive 
angles are measured clockwise; negative angles are measured coun¬ 
terclockwise. 

□ The arc extent, arc, specifies the number of degrees (positive or nega¬ 
tive) spanned by the angle. If the arc extent is outside the range 
[-359,+359], the entire ellipse is drawn. 

Both arguments are expressed in degrees of elliptical arc, with 360 degrees 
representing one full rotation. 

See patnpenjine for use of patterned pen and draw_ovalarc for use oval 
arcs. 
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Syntax 

void patnpen_piearc(w, 

h. 

xieft, ytop, theta, arc) 



short w, h; 

/* 

width and height 



short xieft, ytop; 

/* 

top left corner 



short theta; 

/* 

starting angle (degree) 


Type 

short arc; 

Extended 

/* 

angle extent (degree) 



Description The patnpen_piearc function uses the pen to draw a patterned, pie-shaped 
wedge from an ellipse. The wedge is formed by an arc of the ellipse, and 
by two straight lines that connect the two end points of the arc with the center 
of the ellipse. The ellipse is in standard position, with the major and minor 
axes parallel to the coordinate axes. 

The pen is a rectangle whose width and height can be modified by means 
of set_pensize function. At each point on the arc drawn by the patn- 
pen_piearc function, the pen is positioned so that its top left corner touches 
the arc. The two lines from the center are drawn in similar fashion. The area 
covered by the pen is filled with the current pattern in the current foreground 
and background colors. 

The ellipse from which the arc is taken is specified in terms of the minimum 
enclosing rectangle in which it is inscribed. The first four arguments define 
the rectangle: 

□ The width w 

□ The height h 

□ The coordinates of the top left corner (xieft, ytop) 

The last two arguments define the limits of the arc: 

□ The starting angle, theta, is measured from the center of the right side 
of the enclosing rectangle and is treated as modulus 360. Positive 
angles are measured clockwise: negative angles are measured coun¬ 
terclockwise. 

□ The arc extent, arc, specifies the number of degrees (positive or nega¬ 
tive) spanned by the angle. If the arc extent is outside the range 
[-359,+359], the entire ellipse is drawn. 

Both arguments are expressed in degrees of elliptical arc, with 360 degrees 
representing one full rotation. 

Example See patnpenjine for use of patterned pen and similar call to 

patnfill_piearc. 
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patnpen_point Pattern Pen Point 


Syntax void patnpen_point (x ,y) 

short X, y; /* pen coordinates */ 

Type Extended 

Description The patnpen_point function uses the pen to draw a patterned point. The 
resuiting figure is a rectangle the width and height of the pen, filled with the 
current pattern in the current foreground and background colors. The top left 
corner of the rectangle is located at coordinates (x, y). 

Example See patnpenjine for use of patterned pen and draw_point for drawing 
single pixels. 
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Pattern Pen Polyline patnpen_polyline 


Syntax 


Type 

Description 


Exampie 




typedef struct points_struct 
{ 

short x; 
short y; 

} POINTS; 

void patnpen_polyline(n, points) 
short n; 

POINTS far ^points; 

Extended 

The patnpen_polyline function uses the current pen to draw n patterned 
lines whose endpoints are supplied in an array of structures, described 
in the syntax. 

The function requires two input arguments: 

□ The first argument, n, defines the number of vertices in the polygon. 

□ The second argument, points, is an array in which each pair of adja¬ 
cent 16-bit quantities contains the X and Y coordinates, respectively, of 
a vertex. 

The argument points can be of any length. The application can easily over¬ 
flow the command buffer that is used by the host processorto send the func¬ 
tion parameters to the TMS340. The size of the command buffer is in the 
CONFIG structure (described in Appendix A) returned by the get_config 
function. The application must check that the data sent will not overflow this 
buffer. 

The number of points that can be sent is given by the following formula: 
com_buffer_size (in bytes) - 10 


An alternate entry point patnpen_polyline_a with the same parameteriza¬ 
tion, is also supplied to check the size of the data to be sent. If the command 
buffer overflows patnpen_polyllne_a attempts to allocate a temporary 
buffer in heap. In this way, the application is freed from having to check the 
size of the data being transferred; however, the invocation of the function 
takes longer because the length of the data must be parsed. If there is not 
enough room to store the temporary buffer in TMS340 memory, the error 
function is invoked (which can be trapped by the install_usererror function) 

See patnpenjine for use of patterned pen and similar call to 
draw_polyline for use of polylines. 
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peek_breg 

Syntax 

Type 

Description 


Peek B Register 


long peek_breg(breg) 

short breg; /* B-file register number */ 

Core 

The peek_breg function returns the contents of a B-file register. Argument 
breg is a register number in the range 0 to 15. The function ignores ali but 
the 4 LSBs of breg. The return vaiue is 32 bits. 
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Pen Line pen_line 


Syntax 

Type 

Description 

Exampie 


void pen_line(xl, yl, x2, y2) 

short xl, yl; /* starting coordinates '^/ 

short x2, y2; /* ending coordinates / 

Extended 

The penjine function uses the pen to draw a line. Arguments xi and yi 
specify the starting coordinates of the line; x 2 and y 2 specify the ending 
coordinates. 

The pen is a rectangle whose width and height can be modified by means 
of the set_pensize function. At each point on the line drawn by the penjine 
function, the pen is located with its top left corner touching the line. The area 
covered by the pen is solid-filled in the current foreground color. 

See instali_usererror for similar call to pen_polyllne. 
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pen_OValarc Pen Oval Arc 


Syntax void pen_ovalarc(w, h, xleft, ytop, theta, arc) 

short w, h; /* width and height */ 

short xleft, ytop; /* top left corner */ 

short theta; /* starting angle (degrees) */ 

short arc; /* angle extent (degree) */ 

Type Extended 


Description The pen_ovalarc function uses the pen to draw an arc taken from an ellipse. 

The ellipse is in standard position, with the major and minor axes parallel 
to the coordinate axes. 

The pen is a rectangle whose width and height can be modified by means 
of the set_pensize function. At each point on the arc drawn by the 
pen_ovaiarc function, the pen is located with its top left corner touching the 
arc. The area covered by the pen is solid-filled in the current foreground col¬ 
or. 


Example 


The ellipse from which the arc is taken is specified in terms of the minimum 
enclosing rectangle in which it is inscribed. The first four arguments define 
the rectangle: 


□ The width w 

□ The height h 

□i The coordinates of the top left corner (xieft, ytop) 


ThG laSt two arQUiiiGntS dsfiPiG ths limits Of inG SrCI 


□ The starting angle, theta, is measured from the center of the right side 
of the enclosing rectangle and is treated as modulus 360. Positive 
angles are measured clockwise; negative angles are measured coun¬ 
terclockwise. 


□i The arc extent, arc, specifies the number of degrees (positive or nega¬ 
tive) spanned by the angle. If the arc extent is outside the range 
[-359,+359], the entire ellipse is drawn. 

Both arguments are expressed in degrees of elliptical arc, with 360 degrees 
representing one full rotation. 

See install_usererror for use of drawing pen and draw_ovalarc for use of 
oval arcs. 
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Syntax 


Type 

Description 


Exampie 


Pen Pie Arc pen_piearc 


void pen_piearc(w, h, xleft, ytop, theta, arc) 


short 

w, h; 


width and height 


short 

xleft, ytop; 

/* 

top left corner 


short 

theta; 


starting angle (degrees) 

■k/ 

short 

arc; 


angle extent (degrees) 



Extended 

The pen_piearc function uses the pen to draw a pie-shaped wedge from 
an ellipse. The wedge is formed by an arc of the ellipse and by two straight 
lines that connect the two end points of the arc with the center of the ellipse. 
The ellipse is in standard position, with the major and minor axes parallel 
to the coordinate axes. 

The pen is a rectangle whose width and height can be modified by means 
of the set_pensize function. At each point on the arc drawn by the 
pen_piearc function, the pen is located with its top left corner touching the 
arc. The area covered by the pen is solid-filled in the current foreground col¬ 
or. 

The ellipse from which the arc is taken is specified in terms of the minimum 
enclosing rectangle in which it is inscribed. The first four arguments define 
the rectangle: 

□ The width w 

□ The height h 

□ The coordinates of the top left corner (xieft, ytop) 

The last two arguments define the limits of the arc: 

□ The starting angle, theta. Is measured from the center of the right side 
of the enclosing rectangle, and is treated as modulus 360. Positive 
angles are measured clockwise; negative angles are measured coun¬ 
terclockwise. 

□ The arc extent, arc, specifies the number of degrees (positive or nega¬ 
tive) spanned by the angle. If the arc extent is outside the range 
[-359,+359], the entire ellipse is drawn. 

Both arguments are expressed in degrees of elliptical arc, with 360 degrees 
representing one full rotation. 

See install_usererror for use of drawing pen and patnfill_piearc for use 
of pie arcs. 
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pen_point Pen Point 


Syntax void pen__point (x, y) 

short X, y; /* pen coordinates */ 

Type Extended 

Description The pen__point function uses the pen to draw a point. The resulting figure 
is a rectangle the width and height of the pen and solid-filled with the current 
foreground color. The top left corner of the rectangle is located at coordi¬ 
nates (x,y). 

Example See install_usererror for use of drawing pen and draw_point for drawing 

single pixels. 
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Pen Polyline pen_polyline 


Syntax 


Type 

Description 


Exampie 


typedef struct 
{ 

short x; 
short y; 

}POINTS; 

void pen_polyline(n, points); 
short n; 

POINTS far ^points; 

Extended 

The pen_polyline function uses the current pen to draw lines whose 
endpoints are supplied in an array of structures, described in the syntax. 

The function requires two input arguments: 

□ The first argument, n, defines the number of vertices in the polygon. 

□ The second argument, points, is an array in which each pair of adja¬ 
cent 16-bit quantities contains the X and Y coordinates, respectively, of 
a vertex. 

The argument point s can be of any length. The application can easily over¬ 
flow the command buffer used by the host processor to send the function 
parameters to the TMS340. The size of the command buffer is in the CON¬ 
FIG structure (described in Appendix A) returned by the get_config func¬ 
tion. The application must check that the data sent will not overflow this buff¬ 
er. 

The number of points that can be sent is given by the following formula: 
com_buffer_size (in bytes) -10 


An alternate entry point pen_polyline_a with the same parameterization, 
is supplied to check the size of the data to be sent. If the command buffer 
overflows pen_polyline_a will attempt to allocate a temporary buffer in 
heap. In this way the application is freed from having to check the size of 
the data being transferred. There is a cost, however, in that the invocation 
of the function will take longer since the length of the data has to be parsed. 
If there is not enough room to store the temporary buffer in TMS340 
memory, the error function is invoked (which can be trapped by the in- 
stall_usererror function). 

See install usererror. 
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poke_breg Poke B Register 


Syntax 

Type 

Description 


void poke_breg(breg, value) 

long breg; /* B-file register number */ 

short value; 32-bit register contents */ 

Core 

The poke_breg function stores the 32-bit value in a B-file register. Argu¬ 
ment breg is any register number between 0 and 15. 
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Rightmost One rmo 


Syntax int rmo(n) 

long n; /* 32-bit integer */ 

Type Core 

Description The rmo function calculates the bit number of the rightmost one in argument 
n. The argument is treated as a 32-bit number whose bits are numbered 
from 0 to 31, where bit 0 is the LSB (the rightmost bit position) and bit 31 
is the MSB (the leftmost bit position). 

For nonzero arguments, the return value is in the range 0 to 31. If the argu¬ 
ment is 0, a value of -1 is returned. 


3-137 





seed fill Seed nil 


Syntax int seed_fill(xseed, yseed, buffer, maxbytes) 

short xseed/ yseed; /* coordinates of seed pixel */ 

long buffer; /* GSP pointer to working storage */ 

short maxbytes; /* size of buffer in bytes */ 

Type Extended 

Description The seed_fill function fills a connected region of pixels starting at a speci¬ 
fied seed pixel. The seed color is the color of the specified seed pixel at the 
time the function is called. The connected region is solid-filled with the cur¬ 
rent foreground color. 

□ The first two arguments, xseed and yseed, specify the coordinates of 
the seed pixel. 

The last two arguments specify a buffer used as a working storage during 
the seed fill. 

□ Argument buffer is a buffer large enough to contain the temporary data 
that the function uses. 

Q Argument maxbytes is the number of 8-bit bytes available in the buffer 
array. 

Storage requirements can be expected to increase with the complexity of 
the connected region being filled. 

I-1 

Note: 


Exampie 


The argument buffer is a pointer in TMS340 memory. This area must have 
previously been allocated using gsp_malloc. 


The connected region filled by the function always includes the seed pipcel. 
To be considered part of the connected region, a pixel must both match the 
seed color and be horizontally or vertically adjacent to another pixel that is 
part of the connected region. (A diagonally adjacent neighbor is not suffi¬ 
cient.) 


The seed_fill function aborts (returns immediately) if any of these condi¬ 
tions are detected: 


□ The seed pixel matches the current foreground color. 

□ The seed pixel lies outside the current window register values. 

□ If at any point the storage buffer space specified by maxbytes is insuffi¬ 
cient to continue. 


If the function aborts, it returns the value false (zero); otherwise, it completes 
normally and returns true (nonzero). 

See draw ovalarc. 
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Seed Pattern Fill seed_pat Ilf i 11 


Syntax int seed_patnfill(xseed, yseed, buffer, maxbytes) 

short xseed, yseed; /* coordinates of seed pixel */ 

long buffer; /* GSP pointer to working storage */ 

short maxbytes; /* size of buffer in bytes */ 

Type Extended 

Description The seedjpatnfill function fills a connected region of pixels with a pattern 
starting at a specified seed pixel. The seed color is the color of the specified 
seed pixel at the time the function is called. The connected region is filled 
with the current pattern in the current foreground and background colors. 

□ The first two arguments: xseed, yseed, specify the coordinates of the 
seed pixel. 

The last two arguments specify a buffer used as a working storage during 
the seed fill. 

Qi Argument buffer is a buffer large enough to contain the temporary data 
that the function uses. 

□ Argument maxbytes is the number of 8-bit bytes available in the buffer 
array. 

Storage requirements can be expected to increase with the complexity of 
the connected region being filled. 

I---1 

Note: 

The argument buffer is a pointer in TMS340 memory. This area must have 
previously been allocated using gsp_malloc. 

I_______i 

The connected region filled by the function always includes the seed pixel. 
To be considered part of the connected region, a pixel must both match the 
seed color and be horizontally or vertically adjacent to another pixel that is 
part of the connected region. (A diagonally adjacent neighbor is not suffi¬ 
cient.) 

The seed_patnfill function aborts (returns immediately) if any of these con¬ 
ditions is detected: 

□ The seed pixel matches the current foreground or background color. 

□ The seed pixel lies outside the current window register values. 

□ If at any point the storage buffer space specified by maxbytes is insuffi¬ 
cient to continue. 

If the function aborts, it returns the value false (zero); othenwise, it completes 
normally and returns true (nonzero). 

Exampie See similar call to seed_fill in draw_ovalarc. 


3-139 



select font Select Installed Font for Use 




SyntSX int select_font( id ) 

short id; 

Type Extended 

Description The select_font function selects a previously Installed font for use by the 
text functions. The input argument, id, must be either zero, indicating the 
system OEM font, or a value returned by the install_font function. 

A nonzero value Is returned if the selection was successful, and a zero value 
if the font referred to by id is not installed in the font table. 
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Set Background Color set_bCOlor 


Syntax 

Type 

Description 

Exampie 


void set_bcolor(color) 
long color; 

Core 

The set_bcolor function sets the COLOROB-fileregisterto the color in¬ 
dex replicated by the pixei size of the current configuration. 

See patnfill_piearc. 
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Set_clip_rect Set cupping Rectangle 


Syntax 

Type 

Description 

Exampie 


void set_clip_rect(w,h,xleft,ytop) 

short w,h; /* width, height of clipping rect */ 

short xleft,ytop; /* coordinates of top left corner 

Core 

The set_clip_rect function sets the current clipping rectangle by updating 
the B-file registers WSTART(B5) and WEND(B6) to the dimensions 
specified by the parameters passed. The parameters xieft and ytop are 
relative to the current drawing origin. 

See draw oval. 
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Syntax 

Type 

Description 

Exampie 


Set Foreground and Background Colors set__COlors 


void set_colors(fcolor, bcolor) 
long fcolor; 
long bcolor; 

Core 

Theset_colors function sets both theCOLORt and COLORO B-file regis¬ 
ters to the color indices replicated by the pixel size of the current configura¬ 
tion. 

See get_offscreen_memory. 
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set_COnfig initialize Graphics Configuration 


Syntax int set_config(graphics_mode, init_draw) 

short graphics_mode; 
short init_draw; 

Type Core 

Description The set_config function sets the graphics mode selected by the index 
passed to the default graphics mode, in which the board remains until a 
subsequent call to set_config is made. Different modes can have different 
display resolutions, pixel sizes etc. The get_config function can be used 
to determine the number of board configurations available on a given board 
and the parameters for each configuration. The get_modeinfo function can 
be used to determine the particular configuration parameters for a given 
board.To select a particular mode, this function is invoked with an argument 
of the desired mode number. 

If the graphics mode argument is valid, the new graphics mode is set up 
and the function returns true (nonzero). If the argument is invalid, the func¬ 
tion performs no operation and returns false (zero). 

This function initializes the following TMS340 registers: 

HESYNC to DPYCTL I/O registers Initialized for the current resolution. 

PSIZE I/O register Set to the current pixel size. 

CONVDP I/O register Set to the left-most-one of the dis¬ 

play pitch. 

DPYTAP I/O register Initialized for the board. 

DPTCH B-fiie register Set to the display pitch. 

OFFSET B-fiie register Set to the offset of the current draw¬ 

ing page. 

WSTART B-file register Set to 0. 

WEND B-file register Set to the disp_vres:disp_hres 

value. 

If there is an on-board palette, it is reset to the default colors (see 

lnit_paiet). 

The set_config function also sets the display and drawing pages to page 
0 (for multiple-paged frame buffers). 
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Initialize Graphics Configuration set_COnfig 




•.v.y.Sy.v.y. 


Furthermore if the init_draw flag is set to true (nonzero), the following 
drawing environments are initialized: 

□ The transparency is disabled (in CONTROL I/O register) 

□i Window clipping is set (in CONTROL I/O register) 

□ Pixel Processing is set to replace (in CONTROL I/O register) 

□ PMASK I/O register is set to 0 

□ Foreground color is set to light grey and the background color to black 

□ Source and destination bitmaps are set to the screen 

□ Drawing origin is set to 0,0 

□ Pen width and height are set to 1 

□ Current pattern address is set to 0 

□ All installed fonts are removed and the current selected font is set to 
the system font 

□ Graphics cursor is set to the center of the screen; it is turned off and 
its shape is set to the default shape 

□ Temporary workspace is initialized (see set_wksp) 
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set_CU rs__Shape Set Current Cursor Shape 

Syntax typedef struct 
{ 

short hot__x; 
short hot_y; 
short width; 
short height; 
short pitch; 
long color; 
short mask_rop; 
short shape_rop; 

PTR data; 

}CURSOR; 

void set_curs__shape (shape) ; 
long shape; 

Type Core 

Description The set_curs_shape function initializes the global pointer to the cursor 
shape with the parameter passed to it (which is a pointer in TMS340 
memory). Prior to calling this function, both the cursor shape data and the 
cursor structure must be loaded into TMS340 memory using the 
gsp_mailoc and host2gsp functions. The TMS340 memory address of the 
cursor shape data must be assigned to the data element of the cursor 
structure before loading the structure. The TMS340 memory address of the 
cursor structure can then be passed to this routine to select the cursor. A 
default cursor shape (an arrow) is installed with the graphics manager and 
is available until this routine is called to download a user cursor. The default 
cursor shape can be restored by invoking set_curs_shape with a 
parameter of 0. 

In the set_curs_xy function, (x, y) is the position of the top-left pixel of the 
cursor if hot_x and hot_Y are zero. These values are subtracted from the 
current cursor position to give the top-left hand corner of the cursor starting 
drawing point. For example, in a simple crosshairs cursor of widthf 6 pixels 
and height 12 pixels, the hot_x is set to width/2, that is, 8; and similarly, 
hot_y is set to 6. If the current cursor position is (320, 240), the rectangle 
defining the cursor is drawn with its top left hand corner at 320 - hot_x and 
240 - hot_y, that is (312, 236). This puts the center of the crosshair cursor 
at position (320, 240), the desired cursor position. 

The data that defines the cursor consists of (1) cursor mask data, and (2) 
cursor shape data. This data defining the cursor shape must be contiguous; 
that is, the cursor shape data must immediately followthe cursor mask data. 
The pitch of this cursor data is indicated by the pitch element in the 
CURSOR structure. 
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Set Current Cursor Shape set_CUrs_Shape 


Two raster operators, mask_rop and shape_rop, determine how the cursor 
mask data and cursor shape data, respectively, are expanded onto the 
screen. For the mask data, the background and foreground colors are al¬ 
ways 0 and OFFFFFFFFh, respectively. The color of the cursor shape is de¬ 
termined by the color element in the cursor structure. 

An example of cursor data follows. The mask data consists of an array width 
by height with Os where the cursor is located and 1 s elsewhere. The raster 
op for this data is AND(1). The shape data is an array width by height with 
1 s where the cursor is located and Os elsewhere. The raster op for the shape 
data is OR(8). Typically, the shape of the cursor in the mask data is one pixel 
wider than that of the shape data. This enables the cursor outline to be seen 
when placed over a background of the same color as the cursor shape. 

Example masks for a simple crosshair cursor; 


11111111111 

ii 


00000000000 

— 1 

11110001111 



00000000000 


11110001111 



00000100000 


11110001111 



00000100000 


10000000001 



00000100000 


10000100001 



00111011100 


10000000001 



00000100000 


11110001111 



00000100000 


11110001111 



00000100000 


11110001111 



00000000000 


11111111111 



00000000000 


1 

fiiiiiiliiiiiiil 1 


MASKDATA SHAPEDATA 
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set__CUrs_Shape Set Current Cursor Shape 

Example #include <dos.h> 

#include <conio.h> 

#include <typedefs.h> 

#include <tiga.h> 

#include <extend.h> 

#define ESC OxlB 

CONFIG config; 

char far PencilData[]= 

{ 

OxFF, 0x87, 0x03, 0x00, OxFF,0x03,0x03,0x00,OxFF,0x03,0x02, 0x00,OxFF, 0x01, 0x02,0x00, 
OXFF,0X01,0X03,0X00,OXFF,0X00,0X03,0X00,OXFF,0X80,0X03,0X00,0X7F,0X80,0X03,0X00, 
Ox7F,OxCO,0x03,0x00,0x3F,OxCO,0x03,0x00,0x3F,OxEO,0x03,0x00,OxlF,OxEO,0x03,0x00, 
OxlF, OxFO, 0x03, 0x00,OxOF,OxFO,0x03,0x00,OxOF,0xF8,0x03, 0x00,0x07, 0xF8, 0x03, 0x00, 
0x07,OxFC, 0x03,0x00,0x03,OxFC,0x03,0x00,0x03,OxFE, 0x03,0x00, 0x01,OxFE, 0x03,0x00, 
0x01, OxFF, 0x03, 0x00, 0x00, OxFF, 0x03, 0x00, 0x80, OxFF, 0x03, 0x00, OxCO, OxFF, 0x03,0x00, 
OxEO, OxFF, 0x03, 0x00, OxFO,OxFF,0x03,0x00,0xF8,OxFF,0x03,0x00,OxFD,OxFF, 0x03,0x00, 
0x00, 0x00, 0x00, 0x00, 0x00,0x78, 0x00,0x00,0x00,0xF8,0x00, 0x00, 0x00,OxFC, 0x00, 0x00, 
0x00,0x7C,0x00,0x00,0x00,0x72,0x00,0x00,0x00,0x26,0x00,0x00,0x00,0x39,0x00,0x00, 
0x00,0x11,0x00,0x00,0x80,0x10,0x00,0x00,0x80,0x08,0x00,0x00,0x40,0x08,0x00,0x00, 
0x40,0x04,0x00,0x00,0x20,0x04,0x00,0x00,0x20,0x02,0x00,0x00,0x10,0x02,0x00,0x00, 
0x10,0x01,0x00,0x00,0x08,0x01,0x00,0x00,0x88,0x00,0x00,0x00,0x84,0x00,0x00,0x00, 
0x44,0x00,0x00,0x00,0x4E,0x00,0x00,0x00,0x3E,0x00,0x00,0x00,OxlE,0x00,0x00,0x00, 
OxOE, 0x00, 0x00, 0x00, 0x06,0x00,0x00,0x00,0x02,0x00,0x00, 0x00, 0x00, 0x00, 0x00,0x00 

}; 

CURSOR far pencil = 

{0x0000, OxOOlB, 0x0011, OxOOlC, 0x0020, OxOFL, 1, 8, OL}; 


struct 

r 





\ 

short 

x,y; 


coordinates 


short 

left, right; 


buttons 

*/ 

short 
} mouse; 

xl,yl, x2,y2; 


boundary 



union REGS regs; 
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Set Current Cursor Shape Set_CU rs_Shape 

/* checks for an installed mouse driver */ 

check___mouse () 

{ 

regs.x.ax =0; 

int86(0x33/&regs,&regs) ; 

return(regs.x.ax); 

} 

mouse_driver() 

{ 

/* get mouse coordinates */ 

regs.x.ax = 11; 

int86(0x33/&regs,&regs); 

mouse.X += regs.x.cx; 

mouse.y += regs.x.dx; 

/* ensure the mouse stays within the screen boundary 
if (mouse.X < mouse.xl) 
mouse.X = mouse.xl; 
if (mouse.X > mouse.x2) 
mouse.X = mouse.x2; 
if (mouse.y < mouse.yl) 
mouse.y = mouse.yl; 
if (mouse.y > mouse.y2) 
mouse.y = mouse.y2; 

/* tell the GSP cursor*/ 
set__curs_xy (mouse .x, mouse.y) ; 

/* get the mouse buttons */ 
regs.x.ax = 3; 
int86(0x33/&regs/&regs); 
mouse.left = regs.h.bl & 1; 
mouse.right = (regs.h.bl & 2) » 1; 

} 
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set_curs_shape Set Current Cursor Shape 

install_cursor(type) 

short type; /* 0=default(arrow), l=user(pencil) */ 

{ 

/* Address of user cursor in GSP mem */ 

static PTR UserCurs = OL; 

if(type) 

{ 

/* User cursor type specified */ 

if( UserCurs == OL ) 

{ 

/* Execute this block 1st time only */ 

unsigned short num__bytes; 

/* download cursor shape data to GSP */ 

num_bytes=((pencil.height * pencil.pitch) « 1) » 3; 
pencil.data=(PTR)gsp_malloc(num_bytes); 
host2gsp (PencilData, pencil.data, num_bytes, 0); 

/* download cursor structure to GSP */ 

num_bytes=sizeof(CURSOR); 

UserCurs=(PTR)gsp_malloc(num_bytes); 
hostPgsp (Spencil, UserCurs, num_bytes, 0); 

} 

set_curs_shape( UserCurs ) ; 

} 

else 

set_curs_shape((PTR)0); /*Use default if type-=0 */ 


main () 

{ 

char key; 

short CursorType=l; 

if (check_mouse()) 

{ 

if (set_videomode(TIGA, INIT I CLR_SCREEN)) 

{ 

if (install_primitives() >= 0) 

{ 

get_config(&config); 
printf("Press...\n"); 
printf(" ESC to quit\n"); 

printf(" SPACE to toggle cursor shapesXn"); 
printf(" LEFT mouse button to draw points\n"); 

/* assign a new cursor shape */ 

install_cursor(CursorType); 
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Set Current Cursor Shape set_CUrs_Shape 


/* initialize mouse to the center of the screen 
mouse .x=con fig. mode. disp_hres»l; 
mouse, y = conf ig.mode - disp_vres»l; 
set_curs__xy (mouse. x, mouse. y) ; 

/* intialize mouse boundary 

mouse.xl = mouse.yl =0; 

mouse.x2 = config.mode.disp_hres - 1; 

mouse. y2 = conf ig .mode. disp__vres - 1; 

/* turn on cursor */ 

set_curs_state(1); 
for (;;) 

{ 

/* move the cursor with the mouse */ 

mouse_driver{); 

/'^ if left button pressed draw a point */ 

if (mouse.left) 

draw_point(mouse.x, mouse.y); 
if(kbhit 0) 

switch ( getchO ) 

{ 

case ' ' : 

install_cursor (CursorType"^=l) ; 
break; 
case ESC : 

set__curs_state (0) / /* Turn cursor off */ 
set_videomode(PREVIOUS,INIT); 
exit (0); 

} 

} 

} 

set_videomode (PREVIOUS, INIT) ; 

} 

} 

else printf("Mouse driver required for this example\n"); 

} 
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Set_CUrS_State set Current Cursor State 

Syntax void set_curs_state (enable) 

short enable; 

Type Core 

Description The set_curs_state function displays the cursor (if enable is nonzero) or 

removes it from the screen. 

Exampie See set_curs_shape. 
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Set Current Cursor Position set_CUrs_xy 


Syntax 

Type 

Description 

Exampie 


void set_curs_xy (x, y) 
short x; 
short y; 

Core 

The set_curs_xy function modifies the pixel coordinates of the cursor’s 
hotspot.The cursor coordinates are not relative to the drawing origin; they 
are always relative to the top left hand corner of the screen. 

See set_curs_shape. 
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Set_draw_origin Set Drawing Origin 


Syntax 

Type 

Description 

Example 


void set_draw__origin (x, y) 
short x; 
short y; 

Extended 

The set_draw_origin function sets the drawing origin for all subsequent 
drawing functions. Ail coordinates specified for ail drawing functions are rei- 
ative to the drawing origin. 

See styledjine. 
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Syntax 


Type 

Description 


Set Destination Bitmap set_dstbm 


void set_dstbm(addr,pitch,xext,yext,psize) 
long addr; 
short pitch; 
short xext; 
short yext; 
short psize; 

Extended 

The set_dstbnii function sets the TMS340’s destination bitmap for subse¬ 
quent bitbIt or drawing functions. Invoking the function with an address 
of 0 sets the destination bitmap to the screen. 

The pitch of the destination bitmap must be a multiple of 16. Currently, no 
clipping is performed in a linear bitmap; the calling program must do this. 
Future TIGA revisions will provide this capability. 


3-155 



set_dstbm set Destination Bitmap 


Example #include <typedefs.h> 

#include <tiga.h> 

#include <extend.h> 

CONFIG config; 

/* function to save portion of screen defined by arguments*/ 
/* into a linear bitmap and return the address */ 

unsigned long save__offscreen(width, height, x_left, y_top) 
short width, height, x___left, y__top; 

{ 

unsigned long address; 

address = (PTR) gsp_malloc(((long)width * (long)height * 

(long) config.mode.disp_psize)/8); 

if (address) 

{ 

/* turn off transparency, otherwise pixels of 0 color */ 
/* will not be copied into the destination bitmap */ 

transp_off (); 
set___srcbm(01, 0, 0,0, 0) ; 

set_dstbm(address, width * config.mode.disp_psize, 
width, height, config.mode.disp_psize); 
bitblt(width, height, x_left, y_top, 0, 0); 
set_dstbm(01,0,0,0,0); 

} 

return(address); 


/* function to restore to the screen a pre-saved */ 

/* rectangular region in heap pointed to by address */ 

restore_onscreen(address, width, height, x_left, y_top) 
unsigned long address; 
short width, height, x_left, y_top; 

{ 

if (address) 

{ 

/* turn off transparency, otherwise pixels of 0 color */ 
/* will not be copied into the destination bitmap */ 

transp_off(); 

set___srcbm( address, width * conf ig. mode. disp_psize, 
width, height, config.mode.disp_psize); 
set__dstbm(01, 0, 0, 0, 0) ; 

bitblt(width, height, 0, 0, x_left, y_top); 
set_srcbm(01,0,0,0,0); 

} 

} 
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Set Destination Bitmap set__dstbm 


main () 

{ 

short h, X, y, i; 

PTR save; 

if (set_videomode(TIGA, INIT 1 CLR_SCREEN)) 

{ 

if (install_primitives0 >= 0) 

{ 

get_config(&config); 
clear_screen(LIGHT_MAGENTA)/ 
w = config.mode .disp_hres»4; 
h = config.mode.disp_vres»4; 

X = config.mode. disp_hres»2; 
y = config.mode.disp_vres»l; 

/* save a portion of the screen */ 

save = save_offscreen(w, h, x, y); 

/* clear screen to the current background color */ 
clear_screen(-1); 

X = y = 0; 

/* restore saved region to various places on screen */ 
for (i = 0; i < 8; i++) 

{ 

restore_onscreen(save, w, h, x, y); 

X += config.mode. disp_hres»3; 
y += conf ig.mode. disp_vres»3; 

} 

gsp_free (save) ; 

} 

set_videomode(PREVIOUS, INIT); 

} 

} 
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Set_fCOlor Set Foreground Color 


Syntax 

Type 

Description 

Exampie 




void set_fcolor(color) 
long color; 

Core 

The set_fcolor function sets theCOLORI B-file register to the color index 
replicated by the pixel size of the current configuration. 

See fill_polygon. 
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Syntax 


Type 

Description 


Exampie 


Set Interrupt Handler setjnterrupt 


void set_interrupt(level, priority, enable, scan_line) 
short level; 
short priority; 
short enabled- 
short scan_line; 

Core 

The setjnterrupt function enables/disables a previously installed interrupt 
service routine. The routine must have been installed via the install_rlm 
function or the combination of create_alm and install_alm. 

The level parameter indicates the interrupt level where the interrupt rou¬ 
tine was installed. The priority is returned by the getJsr_priorities func¬ 
tion when the interrupt is installed, to distinguish between different interrupt 
service routines on the same interrupt level. If enable is true (nonzero), the 
interrupt is enabled; otherwise, it is disabled. 

The scan_iine parameter is valid only for display interrupts (interrupt level 
10). It is used to set the line at which the interrupt occurs. If the scan_iine 
parameter is -1, then the value for the scan iine is taken to be that passed 
in the previous invocation of setjnterrupt. This allows the interrupt to be 
enabled/disabled without re-specifying the scan_iine parameter. 

For more details on extensibility and the use of this function, refer to Chapter 
4. 

See Section 4.9. 
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set__palet initialize a Palette 




SSSSSSSSi 


Syntax typedef struct 
{ 

char r; 
char g; 
char b; 
char i; 

}PALET; 

void set_palet(count/ index, palet) 
long count; 
long index; 

PALET far *palet; 

Type Core 

Description The set_palet function loads the palette on the board using the palet 
array. The number of palette entries to be loaded is passed in argument 
count. Argument index designates where the palette loading is to start. 
This allows for a palette to be loaded one piece at a time, rather than all at 
once. The range that is being ioaded is checked by this function to ensure 
that it does not overflow the palette; thus, if the starting index pius the 
number of entries (count) is greater than the palette size, the count value 
is decreased by the appropriate amount. 

In the PALET structure, r, g, and b refer to the red, green, and blue 
values for the colorentry (0 being off and all 1 s being full on); i is an intensi¬ 
ty level for monochrome displays. See also Appendix B.7 for details on color 
selection. 

On systems that store the palette data in display memory (such as those us¬ 
ing theTMS34070), this function reloads every palette data area in the frame 
buffer. Thus, if the system contains multiple display pages, every page is 
loaded by this function. 

Example See similar call to set_palet_entry. 
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Set a Palette Entry set_palet_entry 


Syntax 


Type 

Description 


Exampie 


int set_palet_entry(index, r, g, h, i) 
long index; 
char r; 
char g; 
char b; 
char i; 

Core 

The set_palet_entry function initializes one entry index in a palette. If the 
function aborts, it returns the value false (zero); othenwise, it completes nor¬ 
mally and returns true (nonzero). 

In the palette structure, r, g, b refer to the red, green and blue values for 
the color entry (0 being off and all 1s being full on), and i is an intensity 
level for monochrome displays. See also Appendix B.7 for details on color 
selection. 

On systems that store the palette data in display memory (such as those us¬ 
ing the TMS34070) this function reloads the palette entry in every palette 
data area in the frame buffer. Thus if the system contains multiple display 
pages, every page is loaded by this function. 

See get_palet_entry. 
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Set_patn Set Current Pattern Address 


Syntax 


Type 

Description 


Exampie 


typedef structure 
{ 

ushort width; 
ushort height; 
ushort depth; 

PTR data; 

} PATTERN; 

void set_patn(p) 

PATTERN far *p; 

Extended 

The set_patn function sets the current drawing pattern as specified by the 
PATTERN structure pointed to by p. Currently, only 16x16x1 patterns are 
supported in TIGA’s extended graphics primitives. The application must first 
install its pattern data using gsp_malloc to allocate TMS340 storage 
memory and then use host2gsp to transfer them to TMS340 memory. A 
pointer to the desired pattern in TMS340 memory is then set in the PAT¬ 
TERN structure before calling set_patn. 

See patnfill_piearc. 
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Syntax 

Type 

Description 

Exampie 


SetPensize set_pensize 


void set_pensize(w, h) 

short w, h; /* pen width and height */ 

Extended 

The set_pensize function specifies the width and height of a rectangular 
pen. These dimensions are used for any subsequent drawing operations 
with the pen. 

See install usererror. 
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set__pmask Set Plane Mask 


Syntax 

Type 

Description 


void set_pmask (mask) 

long pmask; /* plane mask */ 

Core 

The set_pmask function specifies the plane mask that is used in subse¬ 
quent drawing operations. The mask determines which bits in a pixel can 
be modified during drawing operations. The Os in the mask enable modifica¬ 
tion of the corresponding bit planes. The 1 s in the mask write-protect the cor¬ 
responding planes. 

The plane mask designates which bits within a pixel are protected against 
writes and affects all operations on pixels. The protected bits are replicated 
for each pixel throughout the 32-bit plane mask. The 1s in the plane mask 
specify protected bits in the destination pixel that cannot be modified, while 
the Os specify bits that can be altered. The plane mask can be read by 
means of a call to the get_pmask function. See the TMS34010 User’s 
Guide for a further discussion of plane masking. 
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Set Pixel Processing Operation set_ppop 

Syntax void set_ppop{ppop_code) 

short ppop_code; /* pixel processing operation code */ 

Type Core 

Description The set_ppop function defines the pixei processing operation for subse¬ 
quent drawing operations. The specified Booiean or arithmetic operation 
determines the manner in which source and destination pixel values are 
combined. The range forthe ppop code argument is 0 to 21. The codes are 
described in the following table: 

Table 3-2. Pixel Processing Options 


Code 

Replace Destination Pixel with: 

Code 

Replace Destination Pixel with: 

0 

source 

11 

NOT source AND destination 

1 

source AND destination 

12 

all Is 

2 

source AND NOT destination 

13 

NOT source or destination 

3 

all Os 

14 

source NAND destination 

4 

source OR NOT destination 

15 

NOT source 

5 

source EQU destination 

16 

source + destination 

6 

NOT destination 

17 

ADDS (source, destination) 

7 

source NOR destination 

18 

destination - source 

8 

source OR destination 

19 

SUBS (destination - source) 

9 

destination 

20 

MAX (source, destination) 

10 

source XOR destination 

21 

MIN (source, destination) 


The TMS34010 User’s Guide (literature number SPVU001) describes the 
details of these operations. 

Exampie See drawjine and zoom_rect. 
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set_srcbm Set GSP’s Source Bit Map 


Syntax 


Type 

Description 


Exampie 


void set_srcbm(addr,pitch,xext,yext,psize) 
long addr; 
short pitch;. 
short xext; 
short yext; 
short psize; 

Extended 

The set_srcbm function sets the TMS340’s source bitmap for subsequent 
bitbIt functions. Invoking the function with the address of 0 sets the source 
bitmap to the screen. 

The pitch of the source bitmap must be a multiple of 16. Currently no clipping 
is performed in a linear bitmap, the calling program must do this. Future 
TIGA revisions will provide this capability. 

See set dstbm. 
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Syntax 

Type 

Description 


Set Text Rendering Attributes set_textattr 


int set_textattr(pControl, count, arg) 
char far ^pControl; 
short count; 
short far *arg; 

Extended 

The seMextattr function sets text rendering attributes, pcontroi is a con¬ 
trol string specifying the attributes to be set. Values associated with attrib¬ 
utes can be specified either as immediate values in the control string, or as 
arguments passed in the array arg. The number of attributes in the control 
string must be passed in parameter count. 

When a values is passed as a string literal, it should be placed between the 
% character and the attribute. For example, to assign the value 1 to attribute 
a enter: 

set_textattr("%la", 1, 0); 

To pass the same value as an argument, an asterisk is placed between the 
% character and attribute, and the value 1 is provided as the first argument 
(element 0) in the passed array: 

short arg[l]; 
arg[0] = 1; 

set_textattr 1, arg[0]); 

The number of attributes successfully set is returned. This is the current list 
of valid attributes: 

Attribute Description _ Option Value _ 

%a alignment 0 = top left,1= baseline 

%e additional intercharacter spacing 16 bit signed integer 
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set__timeout Set Timeout Delay Value 


Syntax 

Type 

Description 

Exampie 


void set_timeout(value) 

short value; value in milliseconds */ 

Core 

The set_timeout function sets the value of the timeout value (in millisec¬ 
onds) that determines how long the host waits for a TMS340 function to 
complete prior to calling the error function with a timeout. The user can ig¬ 
nore timeouts altogether by installing a user error handler function that is 
called when the timeout occurs. This function can be made to ignore such 
timeouts. 

See install usererror. 
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Set Transparency Mode set_transp 

Syntax void set_transp(mode) 

short mode; 

Type Core 

Description The seMransp function, if implemented (on TMS34020 systems only), 
changes the transparency mode. Currently, these are the modes supported 
are: 

mode = 0 Transparency on source equals zero 

mode = 1 Transparency on source equals COLORO 

mode = 2 Transparency on result equals zero 

mode = 3 Transparency on result equals COLORO 

On TMS34010 systems, only mode 2 is supported. 
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set__vectOr Set Contents of GSP Trap Vector 


Syntax unsigned long set_vector(trapnum, newaddr) 

unsigned short trapnum; 
unsigned long newaddr; 

Type Core 

Description The set_vector function writes the specified 32-bit address contained in 
newaddr into the trap vector specified by trapnum. The address originally 
in this trap is returned. This function should be used whenever it is neces¬ 
sary to modify a trap vector address. 
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Set Emulation Mode set videomode 


SyntSX int set_videomode (mode, style) 

short mode; 
short style; 

Type Core 

Description The set_videomode function sets up the video mode to be used. Every 
TIGA application should start with a call to this function with a mode of TIGA 
and the initialize flag set (non-zero) prior to invoking any other TIGA func¬ 
tion. This function sets up the mode to be used in a particular application. 
These are the valid modes: 

TIGA EGA 

MDA VGA 

HERCULES AI_8514 

CGA PREVIOUS 

All TIGA applications should call set_videomode with tiga mode upon 
starting. They should then call set_videomode again at the end of their pro¬ 
gram to restore IBM emulation (since in most cases the board on which 
TIGA is being run is the primary video board). The mode selected could be 
PREVIOUS which restores the emulation mode from a global. However, if a 
particular application wants to switch back and forth between several 
modes, it is recommended that a call be made to get_videomode and the 
mode be saved by the application.The saved mode can be used to terminate 
the TIGA application and to restore the board to the initial state. 

If a call is made to set_videomode and that particular video mode is not 
supported by the board, the routine returns false (zero). 

The style parameter is used to determine the manner in which the mode 
is set up in on entry. This list describes valid styles; 

NOJNIT Used during an application to switch between TIGA and 

other emulation modes. It enters TIGA, leaving all global 
variables intact. 

INIT_GLOBALS Initializes the global variables only, by calling 
set_config with the init_draw flag true and by restoring 
the timeout value and the user error handler. The heap 
pool is retained, which keeps the downloadable exten¬ 
sions installed. 

INIT Initializes global variables and dynamic memory (heap 

pool).This frees all allocated pointers and thus deletes 
all downloaded extensions. 
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set_videonnode Set Emulation Mode 

The style parameter contains one further option, which can be seiected by 
ORing with the above styie parameter: 

CLR_SCREEN This parametershould be used at initialization when you 

are using the INIT_GLOBALS or INITstyles. The screen 
is blanked while the video registers are initialized. 
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Set Windowing Mode set_WinclOWing 


Syntax void set_windowing(enable) 

short enable; 

Type Core 

Description The set_windowing function sets the two-bit windowing code contained in 
the CONTROL I/O register. The windowing codes are 

□ 00 - No windowing 

□ 01 - Interrupt request on write in window. 

□ 10 - Interrupt request on write outside window. 

□ 11 - Clip to window. 

For a more detatiled description of the windowing operation, refer to the 
TMS34010 User’s Gu/ofe (literature number SPVU001). Care must betaken 
in using this function. The extended drawing primitives assume windowing 
option 3 (clip to window) is set. Setting the interrupt request modes (1 and 
2) should only be done after downloading an interrupt service routine for the 
window violation interrupts (see Installing Interrupts in Chapter 4). 
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set_wksp Set a Temporary Workspace 


Syntax 

Type 

Description 

Exampie 


void set_wksp(addr, pitch) 

unsigned long addr; /* starting address */ 

unsigned long pitch;/* workspace pitch */ 

Core 

The set_wksp function sets the workspace environment variables to the 
specified address and pitch. The workspace memory is used by functions 
such as fill_polygon to draw a 1 -bit-per-pixel image of the polygon before 
expanding it to the screen. 

The area used for the workspace may be allocated from offscreen memory 
(a description of which is returned by the get_offscreen_memory function) 
or from from heap using gsp_malloc. It must be large enough to hold a 
1-bit-per-pixel representation of the current screen coordinates with a pow¬ 
er of 2 pitch. 

See fill_polygon. 
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Draw Styled Line Styled_l i ne 


Syntax void styled_line(xl, yl, x2, y2, style, mode) 


short 

xl. 

yl; 


start coordinates 


short 

x2, 

y2; 

/* 

end coordinates 

*/ 

long 

style; 



32~bit line style pattern 


short 

Extended 

mode 

/* 

selects 1 of 4 drawing modes 



Description The styledjine function uses Bresenham’s algorithm to draw a styied line 
from point (xi, yi) to point (x2, y 2 ). The line is a single pixel thick and is 
drawn in the specified line-style pattern. 

□ Arguments xi and yi specify the starting coordinates. 

□ Arguments x 2 and y 2 specify the ending coordinates. 

□ The last two arguments, style and mode, specify the line style and 
drawing mode. 

Argument style is a long integer containing a 32-bit repeating line-style pat¬ 
tern. Pattern bits are used in the order 0,1 ,...,31, where 0 is the rightmost 
bit (the LSB). The pattern is repeated modulo 32 as the line is drawn. A bit 
value of 1 in the pattern specifies that the foreground color is used to draw 
the corresponding pixei. A value of 0 in one of the line style pattern bits 
means that the corresponding pixel is either drawn in background color 
(modes 1 and 3) or not drawn (modes 0 and 2). Four drawing modes are 
supported: 

mode 0 Do not draw background pixels (leave gaps), and do 

load new line-style pattern from style argument. 

mode 1 Draw background pixels in COLORO, and load new lin- 

style pattern from style argument. 

mode 2 Do not draw background pixels (leave gaps), and do re¬ 

use old line-style pattern (ignore style argument). 

mode 3 Draw background pixels in COLORO and re-use old line- 

style pattern (ignore style argument). 

The current style pattern used by the styledjine function is available by 
calling the get_env function. See the get_env function description for more 
information. 
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styled_line Draw styled Line 

Example #include <typedefs.h> 

#include <tiga.h> 

#include <extend.h> 

CONFIG config; 

main () 

{ 

long xl, yl, x2, y2, i, mask; 

if (set_videomode(TIGA, INIT | CLR_SCREEN)) 

{ 

if (install_primitives0 >= 0) 

{ 

get_config(&config); 

/* draw spiral using styled line segments */ 

set_draw_origin (config.mode. disp__hres»l, 
config.mode.disp_vres»l) ; 
x2 = 0; 

y2 = -20 « 16/ 

/* line style pattern */ 

mask = 0x93E493E4; 

styled_line(0, 0, 0, 0, mask, 0); 

for (i == 1500; i > 0 ; —i) 

{ 

xl = x2; 
yl = y2; 
x2 += yl » 4; 
y2 -= xl » 4; 

styled_line (xl»16, yl»16, x2»16, y2»16, 


set_videomode(PREVIOUS, INIT); 

} 

} 
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Swap Source and Destination Bitmaps Swap_bm 


Syntax void swap_bin () 

Type Extended 

Description The swap_bm function swaps the pointers to the structures containing 

the source and destination bitmaps. This is useful for copying bitmap data 
offscreen, then at some later point, swapping the bitmaps and restoring 
the data back onscreen. 

Example See zooin_rect. 
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synchronize Synchronize Host and GSP Communications 


Syntax 

Type 

Description 


Exampie 


void synchronize() 

Core 

The synchronize function ensures that the TMS340 completes all pending 
operations before it returns. TIGA supports two-processor execution and 
some conditions require them to be synchronized. For instance, if the host 
downloads data that is being manipulated by the TMS340, it is essential that 
the TMS340 finishes with it before the host overwrites the data. 

Seeinstail usererror. 


3-178 


TIGA Application Interface 




Syntax 

Type 

Description 


Render an ASCII String text_OLlt 


int text_out(x, y, pString) 
short X, y; 

unsigned char far *pString; 

Core 

The text_out function renders the ASCII string pointed to by pstring in the 
currently selected font using the current set of text drawing attributes. The 
string is a null terminated sequence of 8-bit ASCil character codes. 

The starting position of the string is specified by arguments, x and y. Coor¬ 
dinate X is the position at the left edge of the string, and coordinate y is the 
position at either the top of the string, or the baseiine, depending on the text 
alignment attribute set by a cail to seMextattr. 

The return value is the x coordinate of the next character position to the right 
of the string. If the string lies entirely above or below the clipping rectangle, 
the unmodified starting x coordinate is returned. 



text_width Return Width of an ASCII String 

Syntax int text__width(pString) 

unsigned char far *pString; 

Type Extended 

Description The text_width returns the width of the string in pixels, as if it were rendered 
using the current selected font and the current set of text drawing attributes. 
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Transparency Off transp_Off 


Syntax 

Type 

Description 


Exampie 


void transp_off() 

Core 

The transp_off function disables transparency for subsequent drawing op¬ 
erations. The transparency mode set by default is mode 2, transparency on 
result equals zero (see set_transp function).That is, if the pixel operation 
invoiving source and destination pixels is 0, the destination pixel is not al¬ 
tered. This can be modified forTMS34020 systems by using the seMransp 
function. 

See set dstbm. 
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transp_on 

Syntax 

Type 

Description 


Exampie 


Transparency On 


void transp_on() 

Core 

The transp_on function enables transparency for subsequent drawing op¬ 
erations. The transparency mode set by default is mode 2, transparency on 
result equals zero (see set_transp function) .That is, if the pixel operation 
involving source and destination pixeis is 0, the destination pixel is not al¬ 
tered. This can be modified for TMS34020 systems by using the set_transp 
function. 

See call to transp_off in set_dstbm. 
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Syntax 

Type 

Description 


Wait for Scan Line wait_SCan 


void wait_scan(line) 

short line; /* wait until this scan line is reached */ 

Core 

The wait_scan function waits for a scan line on the CRT to be refreshed. 
This function does not return control to the calling routine until the specified 
line is scanned by the electron beam. Control Is returned at the start of the 
horizontal blanking interval that follows the designated line. Scan lines are 
numbered in ascending order, starting with line 0 at the top of the screen. 
Only visible scan lines are counted. 

This function can be used to synchronize drawing operations to the electron 
beam of a CRT display. For example, when drawing an animated sequence 
of frames, transitions from one frame to the next appear smoother if an area 
of the screen is not redrawn at the same time it is output to the CRT. 

If argument line is less than 0, the function uses the value 0 in place of the 
argument value. If argument line is greater than the bottom scan line, the 
function uses the number of the bottom scan line in place of the argument 
value. 
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ZOOm_rect zoom Rectangle 


Syntax void zooiii_rect (ws, hs, xs, ys, wd, hd, xd, yd, linebuf) 


short ws, hs; /* source width and height */ 
short xs, ys; /* source top left corner */ 
short wd, hd /* destination width and height */ 
short xd, yd; /* destination top left corner */ 
short linebuf; /* scan line buffer */ 

Type Extended 


Description The zoom_rect function expands or shrinks a source rectangle on the 
screen or a linear bitmap to fit the dimensions of a destination rectangle on 
the screen. Horizontal zooming is accomplished by replicating or deleting 
rows of pixels. This type of function is sometimes referred to as a stretch blit. 

The first four arguments define the source rectangle: 

□i The width ws 

□ The height hs 

□ The coordinates of the top left corner (xs, y s) 
ws and hs must be non-negative. 

The next four arguments define the destination rectangle: 

□ Width wd 
Qi Height hd 

□ Coordinates of the top left corner of the rectangle (xd, yd) 
wd and hd must be non-negative. 

The final argument, linebuf, is a buffer large enough to contain one com¬ 
plete line of the display. The function uses the buffer as temporary working 
storage: The minimum buffer size (in bits) is the number of pixels per line 
times the number of bits per pixel. This buffer is a pointer to TMS340 
memory and therefore must be allocated (by calling for example gsp_mal- 
loc) before invoking the function. 

The zoom_rect function can be made to zoom from a linear bitmap by set¬ 
ting the source bitmap global using the set_srcbm function. This function 
only works if the pixel size of the source bitmap is the same as the screen. 
Thus, if the desired effect is to perform a zoom_rect on binary data, this 
must be done in two stages. First download the binary bitmap and use bitbIt 
to expand this to the current pixel size to a linear bitmap. Then perform a 
zoom_rect on this linear bitmap onto the screen. 
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Zoom Rectangle ZOOm__rect 

Example #include <typedefs.h> 

#include <tiga.h> 

#include <extend.h> 

CONFIG config; 

short far arrow_shape[] = 

{ 

0x0003, 0x0007, OxOOOF, OxOOlF, OxOOSF, 0x007F, OxOOFF, 
OxOlFF, OxOSFF, OxOlFF, 0x007F, 0x00F7, 0x00F2, OxOlEO, 
OxOlEO, OxOOCO 

}; 

#define ARROW_W 16 
#define ARROW__H 16 

main () 

{ 

int i; 

PTR arrow_addr_bin, arrow_addr_col, buffer; 
long arrow_size; 

if (set_videomode(TIGA, INIT 1 CLR_SCREEN)) 

{ 

if (install_primitives() >= 0) 

{ 

get__conf ig (&conf ig) ; 

/* set up linear bitmap with binary data for arrow */ 
arrow_size = ARROW_W * ARROW_H; 
arrow_addr_bin = gsp__malloc ( (arrow_size+7) /8) ; 

/* transfer shape data from host to gsp '^/ 

host2gsp(arrow_shape, arrow_addr_bin, 

(arrow_size+7)/8,0); 

/* set up a color bitmap for the arrow shape */ 

arrow__size *= config.mode.disp_psize; 
arrow_addr_col == gsp_malloc((arrow_size+7)/8); 

/* set the source bitmap to the binary arrow shape */ 
set__srcbm(arrow_addr_bin, ARROW__W, ARROW_W, 

ARROW_H,1); 

/■^ set destination bitmap to the color arrow shape 
set_dstbm(arrow_addr_col, ARROW_W * 

config.mode.disp_psize, ARROW_W, ARROW_H, 
config.mode.disp_psize); 

/* blit binary arrow and expand it to color arrow */ 
set_colors(LIGHT_CYAN, LIGHT_BLUE); 
bitblt(ARROW_W, ARROW_H, 0, 0, 0, 0); 
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/* set the source bitmap to the color arrow 
swap_bm(); 

/* set the destination bitmap to the screen 
set_dstbm(01, 0, 0, 0, 0); 

/* set pixel processing to max as the results are 
/* normally better 
set_ppop(20); 

set up zoom-rect buffer to hold 1 scan-line 
buffer = gsp_malloc (config.mode.disp_hres 

config.mode.disp_psize); 

/* now zoom-rect the arrow to the screen 
zoom_rect (ARROW_W, ARROW_H, 0, 0, ARROW_W«2, 
ARROW H, 0, 0, buffer); 


set videomode(PREVIOUS, INIT); 


3-186 


TIGA Application Interface 



Chapter 4 


Extensibility Through the 

User Library 


Extensibility was a prime consideration in the design of the TIGA-340 Inter¬ 
face. TIGA-340 is extensible through the addition or manipulation of its user 
library, which is a collection of C-callable routines compiled or assembled 
with the TMS340 software toolset. 

Graphics standards prior to TIGA have limited the software developer by 
providing a fixed set of graphics drawing primitives. In the rapidly changing 
graphics market, a fixed set of primitives is unacceptable. During the devel¬ 
opment of the TIGA graphics interface, incorporating extensibility into the 
standard was a major design goal. The result was the linking loader de¬ 
scribed in this chapter, which, along with a collection of routines, can be 
used by an application or device driver to install custom-made graphics 
primitives. 
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4.1 Dynamic Load Module 

The key to TIGA’s extensibility is the Dynamic Load Module (DLM). This 
module is a collection of C or assembly routines written by the application 
or device driver programmer, and linked together to form the module. The 
DLM is downloaded at run time into TMS340 memory and integrated with 
the TIGA graphics manager. Once downloaded, each routine contained 
within the module is callable using the same conventions as the TIGA core 
or extended primitives. 

TIGA currently supports two types of dynamic load modules: 

Qi Relocatable load module (RLM), and 
□ Absolute load module (ALM). 

The routines which compose a dynamic load module can be either stan¬ 
dard C-type functions callable from either the host processor or from the 
TMS340, or interrupt service routines called on reception of an interrupt via 
the TIGA standard interrupt handler. 

4.1.1 Relocatable Load Modules 

Relocatable Load Modules (RLMs) are produced directly using the TMS340 
compiler and assembly tools and are in common object file format, or COFF. 
A description of this file format is given in the TMS34010 Assembly Lan¬ 
guage Tools User Guide. These modules contain the necessary relocation 
entries so that they can be loaded anywhere in TMS340 memory. They may 
also contain unresolved references to TIGA core or extended primitives, 
which are resolved when they are loaded. Furthermore, they contain all the 
necessary symbol information stored after loading a symbol table file so that 
subsequent RLMs that are loaded may reference the functions in another 
RLM. The installation of an RLM is performed by invoking the install_rlm 
function which, in turn, invokes tigalnk, the linking loader. 

4.1.2 Absolute Load Modules 

Absolute Load Modules (ALMs) are created from relocatable load modules 
by calling the create_alm function. This function in turn calls the linking 
loader to link and save (instead of link and load) the resultant TMS340 
memory image, tigalnk uses the TIGA heap management routines to allo¬ 
cate a space in TMS340 memory where the ALM will be loaded, tigalnk 
then links and relocates the module to the area starting address in heap. 
Thus, the ALM can only be loaded into this one area in memory. The heap 
area for the module is then freed by the create_altn routine. It is therefore 
imperative that the state of the heap in TMS340 memory is the same when 
the ALM is created as when it is installed. Normally, this can be achieved 
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by always initializing heap prior to calling create_alm and then reinitializing 
heap when the module is installed. Heap initialization can be performed by 
calling set_videomode with an init style. 

The reason for incorporating ALMs into TIGA is that installation of RLMs 
requires the application or device driver written for TIGA to call the 
install_rlm function, which in turn invokes the linking loader. This requires 
about 70 —10OK bytes of free main host memory, depending on the symbol 
table size of the module being installed. For many applications this is the 
most direct and flexible method for installation of functions, as the module 
can be relocated and the symbols accessed by subsequent module loads. 
However, for certain applications and application drivers, not enough 
memory is available to use this method. An example of this is the AutoCAD 
driver, ADI. By the time AutoCAD calls the ADI, all available PC memory 
has been appropriated, leaving no roomforinstall_rlmto invoke the linking 
loader. Using the ALM, no memory is required. The install_alm function 
contains only a short piece of code to load the module into TIGA, since no 
external linking or relocation needs to be made. The create_alm function 
can be called when ADI is installed (at boot time). Because this is prior to 
AutoCAD being invoked, the PC memory is free to invoke TiGALNKto create 
the ALM file. 

When loading an ALM, heap is allocated to store the module. The start ad¬ 
dress is compared to the one returned when the module was created. If they 
are the same ,the ALM is loaded into TIGA; if not, the load is aborted. A 
further restriction with ALMs is, since the symbol information is also no long¬ 
er available within the file (as it is with RLMs), that modules loaded subse¬ 
quently cannot reference functions in an ALM. 
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4.2 Generating a Dynamic Load Moduie 

A TIGA dynamic load module consists of the following three parts: 

□ A collection of C and/or assembly routines, some (or all) of which are 
to become TIGA extensions or interrupt service routines. 

Qj TIGAEXT section declaration. Required only if TIGA extensions are be¬ 
ing declared. 

□ TiGAISR section declaration. Required only if TIGA interrupt service 
routines are being declared. 

This document does not describe the mechanics of generating the TMS340 
source and object code of a user function. This is discussed fully in the 
TMS34010 C Compiler Reference Guide and the TMS34010 Assembly 
Language Tools User’s Guide. If the user library is to contain functions writ¬ 
ten using TMS34010 assembly code then certain guidelines need to be met 
to ensure that the C environment is maintained by the assembly language 
function. For a description of howto interface assembly language routines 
with the C environment, see Section 5.4 of the TMS34010C Compiler Ref¬ 
erence Guide. 

Dependent on whether or not a DLM contains extensions or interrupt ser¬ 
vices routines, one or two specially named GOFF sections must be created 
and linked with the module. If the module contains extensions, the a section 
called TIGAEXT must be created. If the module contains interrupt service 
routines, then a section called TIGAISR must be created. The format of 
these sections is described below. 

4.2.1 TIGAEXT Section 

The TIGAEXT must contain one and only one address reference for each 
extension contained within the module (that is callable from the host). For 
example, if the module contains two functions called my_funci and 
my_f unc 2 the section declared would look like this: 


;TIGAEXT - This COFF section contains references for all ; 
/extensions contained in the module it is linked with. ; 

• • 

/External References 

.globl _my__funcl, _my_func2 
/Start section declaration 
.sect ".TIGAEXT" 

.long _my_funcl /command number 0 within module 
.long _my_func2 /command number 1 within module 
.text /end section 
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4.2.2 The TIGAISR Section 

The TIGAISR section contains two entries for every interrupt service routine 
contained within the module. These entries specify an address reference 
to the ISR and the interrupt number of the ISR. 

For example, if two ISRs called my_inti and my_intio were contained 
within the module, then the section declared would look like this: 


/TIGAISR - This COFF section contains information for all / 
; of the ISRs contained in the module it is linked with. ; 


/External References 

.globl _my_intl, _my_intlO 
/Start section declaration 


sect 

".TIGAISR" 



long 

my inti 



long 

1 

/interrupt number 

1/ 

long 

my intlO 



long 

10 

/interrupt number 

10/ 

text 


/end section 



Note that the TIGAEXT and TIGAISR sections must contain the exact num¬ 
ber of declarations for the external functions to be installed. This is because 
TiGALNK uses the length of these sections to determine the number of decla¬ 
rations. 


4.2.3 Linking the Code and Speciai Sections into an RLM 

Once the user functions have been written, they are compiled and/or as¬ 
sembled, producing a series of COFF object files (. ob j). These files should 
be partially linked together with the object files generated by assembling 
the TIGAEXT and/or TIGAISR sections. Below is an example where two 
functions and two interrupt service routines are created and linked into a 
RLM. 


The source files contain the following: 


myfuncs 
tigaext.asm 
myints.asm 
tigaisr.asm 


Functions my_funcl and my_func2 

References for the above (as in the example) 

Two interrupt routines, my_inti, and my_intio 
References and Trap numbers for the above ISRs 


Step1 : Assemble and/or compile all of the source files: 

cc myfuncs tigaext myints tigaisr |^jj| 

This produces four object files: 


myfuncs.obj 
tigaext.obj 
myints.obj 
tigaisr.obj 
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Step 2: Partially link all the object modules together to form the RLM: 


gsplnk -o EXAMPLE.RLM 
myints.obj tigaisr.obj 


-r - cr myfuncs.obj 


tigaext.obj 


The result of the linking is a relocatable load module entitled example . rlm. 

^ -1 

Note: 

In some versions of the linker, the warning: -Unresolved Reference to 
”_c_init00”. is displayed. It can be ignored. 
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4.3 Installing a Dynamic Load Moduie 

To invoke the commands installed in a dynamic load module, it must first be 
installed into the TIGA graphics manager. The module file is in the form of 
a file in a directory of the host PC. If this directory is not the current working 
directory, the TIGA environment variable must first be set up to point to this 
directory, tigalnk uses the environment variable to find the DLM. The ac¬ 
tual installation procedure differs from RLM to ALM. 

4.3.1 Installing a Relocatable Load Module 

A relocatable load module is installed by the install_rlm function. Below 
is an example program written in Microsoft C which explains how to install 
the example described in the previous section, example.rlm. 

Example 4-1. 

#include <tiga.h> 

main() 

{ 

short module; 

/* initialize TIGA */ 

if (!set_videomode(TIGA, INIT)) 

{ 

printf("Fatal Error - TIGA not installedXn"); 
exit(0); 

} 

/* attempt to install module */ 

if ((module = install_rlm("EXAMPLE")) < 0 ) 

{ 

printf("Fatal Error - couldn't install Example RLM\n"); 

printf("Error code = %d\n", module); 
exit(0); 

} 

/* code to invoke the module functions */ 


set_videomode(PREVIOUS, INIT); 

} 

The install_rlin function is invoked with the filename of the RLM file. Either 
a full pathname can be given, or just the final part of the filename, when ei¬ 
ther the current directory is used or that directory set by the TIGA environ¬ 
ment variable. A default extension of. rlm is assumed unless one is given. 
The install_rlm function will return either the module id for the RLM, which 
will be used when the functions are invoked, or an error code if some error 
occurred. Error codes are negative values, module identifiers are always 
positive (including zero). 
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4.3.2 Installing an Absolute Load Module 

An absolute load module must first be created from a relocatable load mod¬ 
ule. Below is an example program written in Microsoft C that explains how 
to create an ALM from the example described in the previous section. 

Example 4-2. 

#include <tiga.h> 

main () 

{ 

register ret-arn_code; 

if (! set_videomode (TIGA, INIT) ) 

{ 

printf("Fatal Error, TIGA interface not installed.\n"); 
exit(1); 

} 

/* attempt to create the module */ 
return_code = create_alm("EXAMPLE", "EXAMPLE"); 
if (return__code < 0) 

{ 

printf("Fatal Error in creation of 'aim' file\n"); 
printf("Error code = %d\n", return_code); 
exit(1); 

} 

/* further initialization code */ 

set_videomode(PREVIOUS, INIT)/ 

} 

init_driver() 

{ 

register return_code/ 

if(!set_videomode(TIGA, INIT)) 

{ 

printf("Fatal Error, TIGA interface not 
installed.\n"); 

return(0); 

} 

/* attempt to install the module */ 

return_code = install_alm("EXAMPLE"); 
if (return_code < 0) 

{ 

printf("Fatal Error in installation of 'aim' file\n"); 
printf("Error code = %d\n", return_code); 
return(0); 

} 

/* code to invoke the module functions */ 

set_videomode(PREVIOUS, INIT); 

} 
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The example assumes that at the time the program is run initially, tigalnk 
can be invoked by create_alm to produce the ALM file. The invocation pro¬ 
duces an EXAMPLE. ALM file in the same directory as examp le.rlm. Default 
extensions of .rlm and .alm are assumed unless overridden by the file 
names supplied. create_alm produces an ALM file only if it does not al¬ 
ready exist. This generally saves the program the unnecessary time of rec¬ 
reating the ALM every time the program is run. If the application requires 
to create a new ALM, it must first delete the old one explicitly. 

The example also assumes that the part of the program that uses the user 
extensions in the ALM is performed after invoking the init_driver function. 
This scenario is typical with application drivers. The main program actually 
does very little more than initialization and calling the DOS TSR exit func¬ 
tion. Later, the application calls an lnlt_driver type function to get the driver 
ready for subsequent application calls. At this time the TIGA environment 
is re-initialized and the ALM is installed. mstall_alm does not invoke 
tigalnk but uses a trivial loader to move code from the host PC file into 
TMS340 memory. 
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4.4 Invoking Functions in a Dynamic Load Moduie 

The process of invoking a function in a DLM is done in two parts. The first 
part involves the selection of the function, which is described in this section. 
The second part is the actual invocation of the function and the passing of 
its parameters from the host to the TMS340. That part is described in subse¬ 
quent sections. 

4.4.1 Command Number Format 

User extensions that are installed in a DLM are identified by a unique com¬ 
mand number. This command number consists of a 16-bit word split into the 
following fields, as Figure 4—1 shows: 

Figure 4-1. Command Number Format 

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 

-1-1-1-1-1-1-T-1-1-i-1-1-1-1-1- 

_I_ I _I_I_I_I_ I _I_I_I_I_I_I_I_ I _ 

'—V—-V-^-V-' 

function module function 

type number number 

1) The function type (Bits 14—15): 

00 = direct-mode 
01 = C-packet 

10 = reserved for future use 

11 = reserved for future use 

2) The module number (between 0 and 31) (Bits 9 —13): 

31 for TIGA core primitives. 

30 for TIGA extended primitives installed via the install_primitives 
function. 

0 thru 29 for user modules in the order of installation. 

3) The function number within the module (Bits 0 — 8). 

The function type field currently selects between the C-packet mode and di¬ 
rect-mode functions. These two modes determine the manner in which the 
parameters of the function are passed between the host and the TMS340. 
The two modes will be described in subsequent sections. 

The module number is a unique identifier for each module. TIGA supports 
up to 32 DLMs, numbered from 0 to 31. The TIGA core primitives are always 
installed at initialization time as module number 31. Likewise, the DLM that 
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contains the TIGA extended primitives is always assigned module number 
30 by the install_primitives function. The remaining 30 moduie slots, num¬ 
bered 0—29, are assigned to user DLMs as they are Installed. The first user 
DLM installed is assigned the number 0, the second the number 1, and so 
on. 

The function number specifies one of the 512 possible functions that can be 
contained within a module. Function numbers are defined by the order that 
they are declared in the TIGAEXT section within a moduie. For the example, 
described in Section 4.3 my_funci wouid be designated function number 
0, and my_func2 would be designated function number 1. 

4.4.2 Using Macros in Command Number Definitions 

The definition of the command number may be subject to change in future 
versions of TIGA. To minimize the potentiai changes to an application, mac¬ 
ros are provided in the tiga. h include files to enable the command number 
of a function to be specified without referencing the individuai bits in the 
command number. These are the macros: 

CORE_CP (function_nuinber) 

CORE_DM(function_number) 

EXT_CP(function_number) 

EXT_DM (function_nuinber) 

USER_CP(module | function_number) 

USER_DM(module | function_number) 

coRE_cp and coRE_DMselectC-packetordirect-modefunctions with a moduie 
number of 31 (forthe TIGA core primitives). Similarly, ext_cp and ext_dm se¬ 
lect C-packet or direct-mode functions with a module number of 30 (for the 
TIGA extended primitives). user_cp and user_dm are used for user exten¬ 
sions. They take a single argument, which is the module number returned 
by the install_rlm or install_alm function ORed with the function number 
of the function from its position in the TIGAEXT section. The moduie number 
shouid be passed as it is suppiied from the instali procedure. 

These macros shouid aiways be used when specifying command numbers. 
If they are not, and an application hard-codes the bits in a command number, 
there is a risk of incompatibility with future versions of TIGA. 
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4.4.3 Passing Parameters to the TIGA Function 

The invocation of a TiGA function can be done in two ways, depending on 
the type of function cali that is made. These are C-packet or direct-mode 
calis. 

C-packet functions are the easiest of the two to write and have a more flex¬ 
ible parameter format. C-packet functions receive their parameters on the 
stack; thus it is very easy to develop a function that becomes a user exten¬ 
sion by first writing it and debugging it on the host side. The function can then 
be extracted from the host code and be recompiled under the TMS340 C 
compiler. Any parameters it received on the host side will be passed from 
host to TMS340 via a TIGA communication driver routine and then pushed 
onto the TMS340 C stack so that the function behaves just as if it were in¬ 
voked local to the host. To do this, however, extra data must be sent along 
to the TMS340 describing the type and size of each parameter. 

The extra overhead of sending this data, plus the time taken to format the 
parameters and push them onto the stack can be eliminated by using di¬ 
rect-mode. This just sends raw data into the communication buffer used for 
host to TMS340 communication. The user extension function receives on 
the stack a single parameter that is a pointer to the communication buffer 
where the data is stored. The function itself must pick up the data from this 
buffer in the expected format. 

Most applications will be developed using C-packet initially. Those functions 
that are more time critical would be modified to use direct-mode. The 
changes to the source code of an extension to change it from C-packet to 
direct-mode are not that significant as will be seen from examples given lat¬ 
er. The following sections give acomplete description of C-packet and direct 
modes. 
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4.5 C-Packet Mode 

To invoke a User extension using C-packet mode, three pieces of informa¬ 
tion need to be supplied: 

□ The type of call the function uses 

□ The function’s command number 

□ Description of the function arguments 


4.5.1 The Type of Call 

The current C-packet system supports three basic types of function calls: 

cp_cmd This entry point is for functions that do not require any form 
of return data. 

cp_ret This entry point is for functions that require only a single stan¬ 
dard C type return value. 

cp_alt This entry point is for those functions which pass pointers to 
data that is modified indirectly by the function called. 


draw_a_line(xl, yl, x2, y2) 
poly_line(10, &point_list) 
i = read_point(x, y) 
copy_mem( &src, &dst, len) 


would use cp_cmd 
would use cp_cmd 
would use cp_ret 
would use cp_alt 


An additional set of entry points is used when the argument list has the po¬ 
tential of being too large for the size of the communication buffer used to 
transfer parameters between the host and the TMS340. These entry points, 
cp_cmd_a, cp_ret_a, and cp_alt_a, have the same functionality as those 
described above, with the added capability of allocating additional space for 
large amounts of arguments data, at a cost of speed performance. These 
entry points should be avoided when the user knows that the argument 
length of the function in question will not exceed the maximum size dictated 
by the communication buffer’s data size (which is a field of the CONFIG 
structure returned by get_config). 


4.5.2 The Command Number 

Section 4.4.1 on page 4-10 describes in detail the command numberformat. 
The command number should always be specified in the form: 

USER_CP (module | function_number) 

for user C-packet extensions, where module is the module ID of the DLM 
returned at install time and f unction_number is the position of the function 
in the TIGAEXT section. 
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4.5.3 Description of Function Arguments 

To call the desired function, each of that function’s arguments must be un¬ 
derstood by the graphics manager, so data can be passed to the DLM func¬ 
tion in the expected form. Each individual argument is called a packet and 
has its own separate header. Entering the packet headers is made easier 
by the use of additional defines in the tiga. h include file to represent the 
different data types. Below is a list of the currently supported data types: 


WORD(a) 

SWORD(a) 

DWORD(a) 
_BYTE_PTR(b, a) 
_WORD_PTR (b, a) 
_DWORD_PTR (b, a) 
STRING(a) 
_ALTBYTE_PTR(b,a) 
_ALTWORD_PTR (b, a) 
_ALTDWORD_PTR (b, a) 


Immediate WORD argument a 
Immediate signed WORD argument a 
Immediate Double WORD argument a 
BYTE array ptr a with b elements 
WORD array ptr a with b elements 
DWORD array ptr a with b eiements 
Null-terminated string ptr a 
Function altered BYTE array pointer 
Function aitered WORD array pointer 
Function altered DWORD array pointer 


Because the immediate arguments passed in Microsoft C are always pro¬ 
moted to short type, there is no BYTE identifier. If immediate char values 
are passed, eitherthe_woRD or_swoRD identifier should be used. Also, since 
immediate short types are the only data types that need be promoted (to 32 
bits) by the graphics manager, they are the oniy data size to have a signed 
identifier. Ali other arguments’ sign extension requirements shouid be han¬ 
dled by the called routines. 


4.5.4 C-Packet Examples 

The exact argument list of the C-packet entry points is as foilows: 

entry_jpoint_name(CMD_ID, num_packets, packetl, ... , packetn) 


where: 

cm_n-umber command, number 

npackets number of C type packets 

packetl...packetn Packet data (see below) 


Below are some examples of user extensions. These examples are not 
supplied Ti-extended primitives. 
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Example function: 

init_grafix() 

□ The function requires no return data. (Use cp_cmd) 

□ The function’s command number was stored in cmd_id . 
□i The function has no arguments. 

Resulting include file entry: 

#define init_grafix() cp_cmd(DSER_CP(CMD_ID), 0) 


Example function: 

fill_rect(w, h, x, y) 

□ The function requires no return data. (Use cp_cmd.) 

□ The function’s command number was stored in cmd_id . 

□ The function has 4 arguments, all words . 

Resulting include file entry: 

#define fill_rect{w,h,x,y) \ 

cp_cmd(USER_CP(CMD_ID),4,_WORD(w),_WORD(h),_WORD(x) 

Example function: 

poly_line(n, Slinelist) 

□ The function requires no return data (Use cp_cmd.) 

□ The function’s command number was stored in cmd_id . 

□ The function has 2 arguments, woRD,n and word_ptr. 

Resulting include file entry: 

#define poly_line(n,ptr) \ 

cp_cmd(USER_CP(CMD_ID),2,_WORD(n),_WORD_PTR(2*n, ptr)) 


WORD(y)) 


line list. 
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Example function: 

init__matrix (&matrix) 

□ The function initializes the array pointed to by smatrix indirectly. (Use 

cp_alt) 

□ The function’s command number was stored in cmd_id . 

□ The function has 1 argument which points to a 4 x 4 element function 
altered array of longs. 

Resulting include file entry: 

tdefine init_matrix(ptr) \ 

cp_alt(USER_CP(CMD_ID),1,_ALTDWORD_PTR(16,ptr)) 


4.5.5 Overflow of the Command Buffer 

When a command of any kind (primitive or user function) is invoked by an 
application, the communication driverfunctions transfer its parameters from 
host memory into a temporary buffer in the TMS340 memory (called a com¬ 
mand buffer). If one of the parameters of the function is a pointer, then the 
pointer itself is not copied over, only the data that is being pointed to is co¬ 
pied. If the pointer is an array, as in the polyline function, then it can be of 
arbitrary length. Thus, it is very simple for the application to overflow this 
fixed length buffer by, for example, asking TIGA to draw a million element 
polyline. The application must know the size of data that it is attempting to 
transfer into the TMS340 processor memory and check that it will fit in the 
command buffer. For this reason, the command buffer size is included as 
an element in the configuration structure returned by get_conflg. Note that 
if a C-packet entry point is being used, allowances must be made for the 
packet type and size woi'ds, which also use space in the comm.and buffer. 

Memory space management is required for all direct-mode and three regu¬ 
lar C-packet entry points. However, the application can use the_a C-packet 
entry points (for example, cp_cmd_a) which check the size of the parame¬ 
ters and download them in the normal way if they fit. If they do not fit, the 
entry points attempt to allocate a temporary buffer from the heap pool to 
store the parameters. If the allocation is not successful the error function is 
invoked. The checking of the parameter size requires two passes through 
the arguments and thus some speed overhead is incurred using this tech¬ 
nique. However, a rapid real-time function does not commonly use arrays 
too large to tit in the command buffer. 
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Another technique provided in TIGA for the management of large amounts 
of data, which may overflow the command buffer, is the direct-mode entry 
points dm__poly and dmjpoly. These entry points turn the buffer into a cir¬ 
cular queue so that any size of data can download into the buffer. This tech¬ 
nique requires the writing of a custom TMS340 processor command that 
manages the data and the handshaking employed. 
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4.6 Direct Mode 

The principal difference between C-packet and direct modes is that in direct 
mode,when the downloaded function is invoked on the TMS340 side, the 
arguments are not on the stack as in C-packet mode. The downloaded func¬ 
tion is invoked with a single argument, which is a pointer to a data area 
where the host downloaded the parameters. The function itself must fetch 
them from this data area into the local variables.This process makes the 
writing of functions slightly more complicated, but this is offset by the in¬ 
crease in performance. These functions are intended to improve the per¬ 
formance of invoking TIGA extensions from TMS340. They are not meant 
(although they could be used) for functions that are called from other down¬ 
loaded functions from the TMS340 side. Such functions that need to be 
called from both the host and TMS340 (by another downloaded function) 
are best written in C-packet or should have an alternate C-callable entry 
point. 

Note that for the fastest possible transfer of data the direct mode entry 
points do not check the size of the data being transferred. The application 
has to ensure that the data being transferred does not overflow the com¬ 
mand buffer. 

Afurther difference between C-packet and direct mode was that in C-packet 
mode the arguments passed to a function could be of any combination of 
immediate data and pointers in any particular order. This is not the case with 
direct-mode. No packet information is sent with the data, specifying whether 
it is immediate or not, and its size. It is the direct-mode entry point itself that 
determines what format the parameters can be specified in, and, in turn, 
how these parameters are received in the TMS340 communication buffer. 
In the following sections is a list of the direct-mode entry points and the para¬ 
meterization of their arguments. 

4.6.1 Standard Command Entry Point 

void dm_cmd(cmd__number, length, argl, . ., argn) ; 
short cmd_nurtiber/ 
short length; 
short argl...argn; 


This command is the most commonly used for direct-mode commands in 
the TIGA system. It has a single length argument and an arbitrary-length 
list of immediate value arguments: it has no return value. The length speci¬ 
fied is the number of 16-bit words that are sent; thus to send a long, length 
should increase by 2. 
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The TIGA core function poke_breg uses this entry point. It sends a 16-bit 
register number and a 32-bit value to be loaded into the register. Note that 
the length is three, since threel 6-bit words are pushed onto the stack (2 of 
them being the MSW and LSW of value). 

#define poke_breg(regno,value) \ 

cim_cmci (POKE_BREG, 3, (short) (regno) , (long) (value) ) 

The data in the communication buffer looks as follows: 

Figure 4-2. Data Structure of dm_cmd 


16 -blt words 


data -ptr 



regno 


value (LSW) 

value (MSW) 


The poke_breg function has one parameter on the stack, which is 
data_ptr. The function contains the following TMS340 assembly code to 
extract the data from the communication buffer: 

_din_j)oke_breg: 


move 

A0,*-SP,1 

/ 

save AO 



/ 

(Field Size 1 is 32-bits by default) 

move 

*~A14,A8,1 

} 

get data_ptr 

setf 

16,1,0 

/ 

set Field Size 0 to 16-bits 

move 

*A8+,A0,0 

/ 

get regno into AO 

move 

*A8,A8,1 

/ 

get value into A8 
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4.6.2 Standard Command Entry Point with Return 

unsigned long dm_ret(cmd_number, length, argl, ... , argn); 
short cmd_number; 
short length; 
short argl...argn; 

This command is simiiar to dm_cmd described in Section 4.6.1 on page 
4-18. The difference is that after caiiing the TMS340 function, the host waits 
for the command to finish, and then fetches and returns the standard C re¬ 
turn vaiue. The vaiue is returned as a iong, but is of the same type as that 
returned by the caiied routine (signed or unsigned, etc.). The vaiue is re¬ 
turned in the DX:AX registers. As with dm_cmd, dm_ret specifies iength 
in 16-bit words. 

The TiGA core primitive get_nearest_color uses this entry point, it sends 
4 bytes of red, green, biue, and intensity (which are aii promoted to shorts 
by the C-compiier), returning a iong index into the paiette. 

dm_ret (GET_NEAREST_COLOR, 4, (short) (r) , (short) (g) 

(short) (b), (short) (i)) 
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4.6.3 Standard Memory Send Command Entry Point 

void dm_jpsnd (cmd_number, length, ptr) 
short cmd_number/ 

short length; 

char far *ptr; 

This command is used to cali functions that require information in the form 
of an array or structure. Note that in this case the iength specified is in bytes, 
not 16-bit words as in the previous two entry points. The ptr argument is 
a far pointer into host memory. The contents of this pointer are down loaded 
into the communication buffer. 

The TIGA extended primitive draw_polyline uses this entry point. Notice 
that the numpts is multiplied by 4 since every point consists of two coordi¬ 
nates (x and y), each of which is 2 bytes long. 

#define draw_polyline(numpts,pts) \ 

dm_psnd(DRAW_POLYLINE,(short)(4*(numpts)), \ 

(short far *)(pts)) 

The data in the communication buffer looks as follows: 

Figure 4-3. Data Structure of dm jpsnd 



X coordinate of first point 
y coordinate of first point 
X coordinate of second point 
y coordinate of second point 
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Because the entry point always sends the byte count into the first word of 
the communication buffer, the TMS340 function itself must scale it to a 
point-count by dividing the value by 4. The primitive contains the following 
TMS340 assembly code to extract the data from the communication buffer: 

_dm_draw_polyline: 


move 

*-A14,All, 1 

; get data_jptr 

setf 

16,1,0 

/ set field Size 0 to 16-bits 

move 

*A11+,A10,0 

; 1st word is number of bytes 
; the post-increment of All means 
; it is now a pointer to pts[0] 

srl 

2,A10 

; convert to numpts 
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4.6.4 Standard Memory Return Command Entry Point 

unsigned long cim_pget (cmd_number, length, ptr) 
short cmd_number; 

short length; 

char far *ptr; 

This command is used to call functions that return information in the form 
of an array or structure. The length (in BYTES) is sent as the first element 
in the command buffer and invokes the TMS340 function. The function 
writes the return data into the communication buffer at the word following 
the length. 

The TIGA core primitive get_palet uses this entry point. Notice that the 
nument parameter is multiplied by 4 since each palet entry consists of a red, 
green, blue, and intensity byte. 

#define get_palet(nument,pal) \ 

dm_pget(GET_PALET,(short)(4*(nument)),(char far *)(pal)) 

The data in the communication buffer contains the one word of data before 
the function is invoked: 


Figure 4-4. Data Structure Before Invoking dm_pget 


data_ptr 


16-bit words 
nument « 4 


Following the invocation of the buffer the communication buffer contains: 

Figure 4-5. Data Structure After Invoking dm_pget 


16-bit word 


data^ptr 


nument « 4 

paitOl.g 

: pailOJ.r 

pallO).f : 

paliOl.b 


red and green vaiues of first entry 
biue and intensity of first entry 


I 


I 

I 


4-23 




Direct Mode 


4.6.5 Standard String Entry Point 

void dm_jpstr (cmd_number, ptr) 
short cmd_number; 

char far *ptr; 

This command is simiiarto dm_psnd, but instead of sending a pointer with 
a known length, it sends a null-terminated string. In this case, the communi¬ 
cation buffer has no length entry as the first word. Successive bytes of the 
buffer contain the characters in ptr with a null (zero) terminator. 

An example for this entry point can be found in the communication entry 
points tests in the TIGA release (in directory tigapgms\tests\coms). 

4.6.6 Altered Memory Return Command Entry Point 

unsigned long din_palt (cmd_number, length, ptr) 
short cmd_nuiiiber; 

short length; 

char far *ptr; 

This command is used to send and return information in the form of an array 
or structure. This entry point combines the functionality of the dm_psnd 
and dm_pget entry points to send the contents of a pointer (of length by¬ 
tes), which is then modified by the TMS340 function. When it completes the 
data is returned back into the host memory pointed to by ptr. 

An example for this entry point can be found in the communication entry 
points tests in the TIGA release (in directory tigapgms\tests\coms). 

4.6.7 Send/Return Memory Command Entry Point 

unsigned long din_ptrx (cind_nuinber, send_length, send_ptr, 
return_length, return_ptr) 
short cmd_number; 

short send_length; 

char far *send_ptr; 

short return_length; 

char far *return_ptr; 

This command is used to send information in an array or structure and return 
information to a different array or structure. It is simiiarto dm_palt in Section 
4.6.6 except that data is returned to a different area of host memory. 

An example for this entry point can be found in the communication entry 
points tests in the TIGA release (in directory tigapgms\tests\coms). 
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4.6.8 Mixed Immediate and Pointer Command Entry Point 

void dm_jpcmd (cmd_number, num_words, wordl, word2, . . . 



num_ptrs, 

cntl. 

ptrl, cnt2, ptr2, 

. . .) 


short 

cmd_number 

; /* 

command number 


V 

short 

num words; 

/* 

number of words to send 


short 

short 

wordl; 

word2; 

/* 

immediate data 


*/ 

short 

num_j)trs; 

/* 

number of pointers 

to send 


short 

cnt 1 ; 

/* 

number of bytes in 

pointer 1 

*/ 

char far 
short 
char far 

^ptrl; 

cnt2; 

’*'ptr2; 

/* 

pointer data 


V 


This command combines immediate and pointer data. The first parameter 
after the command number is the number of words ( num_words ) to send in 
the same manner as dm_cmd. Following that are the words themselves 
on the stack. After the immediate data is a count of the number of pointers 
to send (nuin_ptrs). Each pointer is preceded by a count of the number of 
bytes contained in the array or structure that the pointer is pointing to. 

An example for this entry point can be found in the communication entry 
points tests in the TIGA release (in directory tigapgms\tests\coms). 


Mixed Immediate and Pointer Command Entry Point with Return 


unsigned long dm pret(cmd 

number, 

, num words, wordl, word,... 



num ptrs, 

, cntl. 

ptrl, cnt2, ptr2, ..) 


short 

cmd_numbers; 

/* 

c omman d_numb e r 


short 

num_words; 

/* 

number of words to send 


short 

wordl; 

/* 

immediate data 


short 

word2; 




short 

num_ptrs; 

/* 

number of pointers to send 


short 

cnt 1; 

/* 

number of bytes in pointer 1 


char far 

*ptrl; 

/* 

pointer data 


short 

cnt2; 




char far 

*ptr2; 





The command dm_pret is similar to dm_pcmd except that it returns a stan¬ 
dard C value in the DX:AX registers. 

An example for this entry point can be found in the communication entry 
points tests in the TIGA release (in directory tigapgms\tests\coms). 
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4.6.10 Poly Function Command 


void dm_poly(cmd_number, packet_number, packet_size, packet_ptr) 
short cmd_number; 

short packet_nuiTLber; 

short packet_size; 

char far *packet__ptr 


This entry point is different from every other C-packet and direct-mode entry 
point in that it does not simply transfer data from host to TMS340 memory 
and invoke a command. This command is used for operations that require 
a large amount of data to be transferred and when a certain degree of par¬ 
allelism is possible: that is, some of the data being sent can be processed 
while the rest is being sent down. Forexample.the ADI redraw function used 
by the TIGA AutoCAD driver uses this entry point to draw some vectors 
while others are being sent by the host. 

The command buffer used by the communication driverto download the pa¬ 
rameters is turned into a circular queue of packets. The command buffer 
contains the following: 


Figure 4-6. Data Structure of dm_poly 

datajJtF— 


16-bit words 


total number of packets 


number of packets in a burst 


packets sent 


packets used 


start of packet 1 


This entry point sends a burst of packets down from the host to the TMS340. 
It updates the packets-sent count and monitors the packets-used count to 
ensure that there is enough room to download more packets. The userfunc- 
tion must be specially written to comprehend this handshaking scheme and 
be responsible for the update of the packets used entry. 
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Example 4-3. 


TIGA - Graphics Manager function 


; Usage; Example GSP shell routine with cim_j)oly entry point. 


; Include GSP register definitions 
.copy gspregs.inc 

; Include macros 

.mlib gspmac.1ib 

; Declare globals 

.globl _example_dmpoly 

; External References; Arguments Received from Host 
aTOTAL .set 0 /total number of packets 

aPAGE .set lOh /packets per page 

aSENT .set 20h /packets sent 

aUSED .set 30h /packets used 

aDATA .set 40h /data starts here/ Register usage 

Rarg .set AO /pointer to arguments 

Recurrent .set A1 /count (current) 

Rctotal .set A2 /count (total packets) 

Rctemp .set A3 /count (temp) 

Repage .set A4 /count (total per page) 

Rdata .set A5 /pointer to data 

BURST_SIZE .set 16 

_example_dmpoly: 

mmtm SP,A0,A1,A2,A3,A4,A5,A6,A7,A9 
Pope Rarg /get pointer to args 

move *Rarg(aTOTAL),Rctotal,0 /get total packets 

move *Rarg(aPAGE),Repage,0 /get packets per page 

clr Recurrent /clear current count 

page_loop: 

move Rarg,Rdata 

addi aDATA,Rdata 

Push Repage 

burst_loop: 

movk BURST_SIZE,Rctemp /Rctemp is number pkts 

sub Rctemp,Rctotal 

jrge full_burst 

add Rctotal,Rctemp 

clr Rctotal 

full_burst: 

add Rctemp,Recurrent /current count up to date 

check_loop: 

move *Rarg(aSENT),A8,0 /Get count ready 

sub Recurrent,A8 /Sub off desired count 

jrlt check_loop /If not ready, then wait 
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JAWS: 


packet_ 

loop: 


/ 

; Grab 

some 

data and do something with it 

/ 

move 

*Rdata+,A6,1 


move 

*Rdata+,A7,1 


move 

*Rdata+,A9,0 

/ 

ds js 

Rctemp,packet loop 


move 

Recurrent,*Rarg(aUSED),0 


move 

Rctotal,Rctotal 


jrz 

exit 


subk 

BURST_SIZE,Repage 


jrgt 

burst_loop 


Pop 

Repage 


jruc 

page loop 

exit: 

Pop 

Repage 


mmfm 

SP,AO,A1,A2,A3,A4,A5,A6,A7,A9 


rets 

2 


4.6.11 Immediate and Poly Data Entry Point 

void din_ipoly (cmd_number, nShorts, sData, . . ., ItemSz, 
nltems, pData) 

unsigned short cnid_number; /* command number 
unsigned short nShorts; /* Number of immediate short 

words to send */ 

unsigned short sData; /* First short word of data 

to send */ 


unsigned short ItemSz; /* Size of items that follow 

(in bytes) '^/ 

unsigned short nltems; /* # of items that follow */ 

char far *pData; Pointer to data to send */ 

This entry point is similar to dm_poly; it is used for operations that require 
a large amount of data items to be transferred, and the TMS340 has the abil¬ 
ity to operate on 1 or more data items at a time. Some of the data can be 
processed by the TMS340 while more is being sent down. 

A user function located on the TMS340, which expects data sent by this 
entry point, must be coded using a specific set of rules. When the TMS340 
function is called, it will receive a data pointer in TMS340 memory. The data 
at that address will consist of the immediate data values. The poly data that 
is sent in bursts by the host requires special processing and communication 
protocol inorderto be received. In order to isolate this from the userfunction, 
a service routine is provided called srvjpoly. This service routine should 
be called, once the user function is ready to process the poly data. The pa¬ 
rameters for this function are as follows: 

srv_ipoly(pItemSrv, pDataBuf) 

void (*pItemSrv)(); /* Ptr to item handler */ 

char *pDataBuf; /* Address after last immed. word */ 

The pDataBuf argument is the address immediately following the last im¬ 
mediate word received by the user function. 
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The pitemsrv is the address of a function that can, in turn, be called by 
srvjpoly to handle 1 or more Items. This function will be called repetitively 
by srvjpoly until all the items have been received by the host and serviced. 
This function will be called with the following arguments: 

(*pItemSrv)( nitems, pitems); 

unsigned short nltems; /'^ Number of items this time '^/ 
char *pltems; /* Pointer to data 

The nltems argument is the number of items requiring service. The pitems 
argument is the address of a data buffer containing nltems worth of data. 

The following is an example of how this entry point can be used. For this ex¬ 
ample, a polypixel command is implemented The function has 2 immediate 
arguments, the foregound color of the pixel, and the raster op to be used to 
draw the pixels. The remaining poly data is an array of points where pixels 
are to be drawn. 

The host program to call the entry point would look like this: 

dm_ipoly(CMD, 2, color, rop, 4, nPoints, pData) 

where: 

CMD 
2 

color 
rop 
4 


nPoints 

pData 


Command number of the polypixel function. 

Specifies that two immediate arguments follow: color and rop. 
First immediate argument. 

Second immediate value. 

Each item is a point, which in this case is two words. The first 
specifies the X coordinate, the second specifies the Y. The size 
of the item is therefore 4 bytes. 

Specifies the number. 

Pointer in host memory where the point resides. 
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The downloaded TMS340 user function called polypixel looks like this: 


TIGA - POLYPIXEL - Example User function 


; Example of a downloaded GSP function which uses the 
; dm_ipoly host entry point. 


; Include GSP register definitions 
.copy gspregs.inc 

; Include macros 

.mlib gspmac.lib 

; Declare globals 

.globl _PolyPixel 

/ External References 

.globl _srv_ipoly 

; Polypixel argument definition 
aCOLOR .set 0 

aROP .set lOh 

aDATA .set 20h ; address passed to srv_ipoly 


PolyPixel: 


mmtm 

SP,A0,A1,A2 



setf 

16,0,0 



move 

@CONTROL,A2,0 

;save CONTROL register 

Pope 

AO 

; get 

pointer to data 

move 

*A0(aCOLOR),A1,0 

;get 

color 

move 

A1,COLORl 

; set 

gsp foreground color 

move 

*A0(aROP),Al,0 

/•get 

raster op 

setf 

5,0,0 



move 

Al,@CONTROL+10,0 

;use 

it to set gsp pp op 

setf 

16,0,0 




; Ready for poly data, push the address following the 
; immediate data and the address of the service routine 


Push 

STK 



move 

AO, A8 



addi 

aDATA, A8 



Pushc 

A8 

;push 

data address 

movi 

drawpixels,A8 



Pushc 

A8 

;push 

item service routine 

calla 

srv ipoly 



All done, cleanup and 

exit 


move 

A2,©CONTROL,0 

/restore CONTROL register 

mmfm 

SP,A0,A1,A2 



rets 2 
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; Item service routine: drawpixels 
/ 

; This function is called repetitively by the srv_ipoly 
; function until all the items sent by the host have been 
; received and serviced. This function is called with two 
; stack parameters, the 1st parameter is the number of 


/ items requiring service, and 
; address of the data items in 


drawpixels: 


mmtm 

SP,B10,B11,B12,B13 

move 

STK,B13 

move 

*-B13,B10,l 

move 

*-B13,Bll,1 

move 

B13,STK 

drawloop 


addk 

l,COLORl 

move 

*B11+,B12,1 

pixt 

COLORl,*B12.XY 

ds js 

BIO,drawloop 

mmfm 

SP,B10,B11,B12,B13 

rets 

2 


the 2nd argument is the 
340 memory. 


;save registers 

;pop number of items 
;pop ptr to item data 


;get Y:X pixel coords 
;draw a pixel 

;loop until items exhausted 
;restore registers 
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4.7 Downloaded Function 

User extended routines and interrupt service routines contained in adynam¬ 
ic load module have the ability to access functions or globals which were 
previously installed into TIGA. This includes the core primitives and the Tl 
extended primitives (provided that they have been installed by the applica¬ 
tion). Note that certain primitives are host-only primitives and cannot be 
invoked by a dynamically loaded routine. These are 


create_alm 

create_esym 

field_extract 

fieldjnsert 

flush_esym 

flush_extended 

get_lsr_priorities 

get_modeinfo 

get_videomode 

gsp2host 

gsp2hostxy 


host2gsp 

host2gspxy 

install_alm 

install_primitives 

install_rim 

install_usererror 

set_config 

set_timeout 

set_videomode 

synchronize 


The downloaded function, whether written in TMS340-C or assembly lan¬ 
guage, can take advantage of all the facilities of the graphics manager, spe¬ 
cifically it can 


1) Invoke nearly all the TMS340 primitive functions as if they were written 
on the host side. Thus, it can invoke the function set_palet with the 
parameters used in Microsoft C. Not all the primitives can be invoked 
from the TMS340 side since some require access to host side data 
structures, such as those concerned with the linking loader. Two in¬ 
clude files containing the graphics manager core functions and ex¬ 
tended functions (gsptiga.h and gspextnd.h) are supplied for this pur¬ 
pose. This capability has the advantage that an application can be writ¬ 
ten and debugged on the host side using Microsoft debug tools and 
then individual functions can be downloaded onto the TMS340 side with 
no changes. 

2) Access global variables of the graphics manager, such as those speci¬ 
fying display coordinates, directly without invoking functions to do it. An 
include file containing the graphics manager global variables 
(gspgiobs .h) IS Supplied forthis purpose. The file is shown in the fig¬ 
ure below, which details the global variables that the downloaded exten¬ 
sion is free to access in the current version of TIGA. 
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extern long bottom_of_stack; 

extern CONFIG config; 

extern PALET DEFAULT_PALET[16]; 

extern CURSOR DefaultCursor; 

extern long end_of_dram; 

extern ENVIRONMENT env; 

extern ENVCURS envcurs; 

extern ENVTEXT envtext; 

extern MODEINFO *modeinfo; 

extern MONITORINFO *monitorinfo; 

extern MODULE Module[32]; 

extern OFFSCREEN_AREA *offscreen; 

extern PAGE *page; 

extern PALET palet[]; 

extern PATTERN pattern; 

extern char *setup; 

extern short sin_tbl[]; 

extern long stack_size; 

extern long start_of_dram; 

extern FONT sysfont; 

extern PACKET *sys_free; 

extern long *sys_memory; 


/* declared in link file */ 
/* current configuration */ 
/* default palette */ 
/* default cursor struct */ 
/* declared in link file */ 
/* environment variables */ 
/* cursor environment */ 
/* text environment */ 
/* operating mode info */ 
/* monitor timing info */ 
/* function module descr. */ 
/* pointer to current data */ 
/* pointer to current data */ 
/* current palette in use */ 
/* current pattern info. */ 
/* current setup pointer */ 
/* sine look-up table */ 
/* declared in link file */ 
/* declared in link file */ 
/* system font */ 
/* pointer to free packets */ 
/* pointer to heap packets */ 


Where these variables reference a specific type of declaration, such as 
PALET, the include file gsptypes.h should also be included to define this type 
of declaration. 

4.7.1 Register Usage Conventions 

Assembly language functions used in conjunction with the TIGA primitives 
should follow certain guidelines for register use. The following registers 
must be restored to their original states (the state before the function was 
called) before control is returned to the calling routine: 

□ Status register fields FE1 and FS1 must be restored. Fields FEO and 
FSO need not be restored. 

□ All A-file registers except A8 must be restored. A14 should not be used 
as a temporary variable by a user function. It must always contain a 
pointer into the C parameter stack, because an interrupt service routine 
(ISR) may interrupt a user function, and that ISR may cali a C function 
using the C stack. 

□ In general, all B-file registers must be restored. However, certain B-file 
registers may be altered by attribute control functions that update pa¬ 
rameters such as COLORO and COLOR1. 

□ In general, I/O registers CONTROL, DPYCTL, CONVDP, and INTENB 
should be restored before returning to the calling routine. However, 
some I/O register bits may be altered by attribute control functions that 
update parameters such as the plane mask, pixel processing operation, 
or transparency flag. These register bits typically are not changed by 
graphics output functions. 
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Upon entry to a downloaded extension, certain registers are in a known 
state and contain well-defined parameters. These assumptions cannot be 
made of interrupt service routines, since they can interrupt a function that 
may be using one of these registers for a different purpose. Extensions, 
however, can assume that the following registers are in these states: 


□ Status register: 

■ FE1 = 0 

■ FS1 = 32 

■ FEO and FSO are undefined 

Q A-File Registers: STK - A14 points to the C-parameter stack. 

□ B-fiie registers: 

DPTCH Screen pitch (difference in starting memory addresses of 
any two successive scan lines in display memory). 

OFFSET Memory address of pixel at top left of screen. 

WSTART Top left corner of current window. 

WEND Bottom right corner of current window. 

COLORO Source background color. 

COLOR1 Source foreground color. 

□i I/O registers: 

CONTROL Contains current pixel processing operation code and 
transparency control bit. These are set by the application 
program and may vary from one call to the next. In con¬ 
trast, in the window mode, PBH and PBV bits are set to 
specific values. The window mode is set to enable clip¬ 
ping without interrupts (W=3). The PBH and PBV bits are 
both zero. 

CONVDP Is set up for the screen pitch. 

PMASK Contains the current plane mask. 
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4.7.2 TIGA Graphics Manager System Parameters 

The TIGA graphics manager assumes that certain system parameters are 
under its control. Dynamic load modules should not alter the following regis¬ 
ters: 

□ The master interrupt enable bit (IE) in the status register. 

□ The cache disable bit (CD) in the CONTROL register. 

□ The DRAM refresh control bits (RR and RM) in the CONTROL register. 

□ The four host interface registers (HSTADRL, HSTADRH, HSTDATA, 
and HSTCTL). 
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4.8 Example Programs 

The TIGAPGMS directory that is shipped with TIGA contains several exam¬ 
ple functions. To gain the maximum benefit from the foiiowirig sections of 
this guide, they should be read in conjunction with a hard copy of the listings 
of the source code of those examples. 

4.8.1 Stars Example 

The TIGA release disk with the example programs contains a stars directory 
that is an example of the use of C-packet and direct-mode extensions of 
TIGA. This demonstration program may be familiar because it has been 
ported to many different graphics environments. It basically consists of mov¬ 
ing through a three-dimensional galaxy in which stars grow larger as they 
are approached and then disappear off the edge of the screen. As they do 
so, new stars are created in the distance. This scenario is performed in four 
ways. First, using host calls to TIGA extended primitives to perform the 
drawing of the stars. Second,where the host calls to a custom TMS340 C 
routine using the C-packet communication mechanism. Third, where the 
host calls a custom direct-mode C routine. Finally, where the direct-mode 
routine has been re-written using TMS340 assembly code. The stars pro¬ 
gram prints out the elapsed time to call these different functions, and the 
time saving is evident. It should be noted at the outset that this example, 
though demonstrating the capabilities of downloading TIGA extensions, is 
very artificial. The time savings in a real application is typically better than 
with this example, especially when the downloaded function performs 
something a little more substantial than drawing a few pixel-wide stars. 

This example consists of the following source files: 

stars. c Main program (Microsoft-C) 

star.h Insert file containing type definitions and external refer¬ 

ences 

data.c Star shapes 

starscp. c C-packet extension to draw a star (TMS340-C) 
starsdm. c Direct-mode extension to draw a star (TMS340-C) 
starsasm.asm Direct-mode extension to draw a star {TMS340-assembly) 
starsgsp. asm TIGAEXT file describing extension routine names 


4-36 


Extensibility Through the User Library 



Example Programs 






The routine that forms the downloaded extension is one that draws a single 
star. The four versions of it are 


draw_star_host 
draw_star_cp 
d r a w_s t a r_dm 
draw star asm 


in file stars.c 
in file starscp. c 
in file starsdm. c 
in file starsasm.asm 


Acomparison between the draw_star_host and draw_star_cpshowsthat 
besides the function name, the two are identical (apart also from the more 
important fact that one is compiled in Microsoft C and the other in TMS340 
C). This underlines an important advantage of TIGA: that it is possible to 
take an existing application running under Microsoft C, move a function to 
the TMS340 side, and invoke it with the same parameterization as if it were 
locally resident and obtain an immediate speed improvement, as can be 
seen from running this program. Further speed improvement can be accom¬ 
plished with just a little more work. 

A comparison between the draw_star_cp and draw_star_dm functions 
shows that after the first four lines of the direct-mode version, the functions 
are again identical. The only difference between them highlights the funda¬ 
mental difference between C-packet and direct-mode functions. Direct¬ 
mode functions receive parameters, just as the host downloads them, as 
sequential items in a communication buffer. The direct-mode function re¬ 
ceives a single parameter, which is a pointer to the data area of the commu¬ 
nication buffer where the data has to be fetched. In the C-packet case, the 
functions parameters are sent down in packets describing the size and type 
of the data being sent. Then a C-packet interpreter parses these packets 
and pushes parameters onto the stack where the C-packet extension ex¬ 
pects to find them. This enables the C-packet routine to be called just as if 
it were local to the host program, but it incurs the additional time overhead 
of sending more information in the packet than the data itseIf.The di¬ 
rect-mode extension eliminates this overhead but puts a very slight extra 
burden on the extension to fetch its own data. Because the transition from 
C-packet to direct mode is very simple, it is expected that most applications 
will use C-packet to start and then move to direct mode forthose time-critical 
functions that need to be optimized. 

The final function draw_star_asin also uses direct mode, but the function 
no longer uses the TIGA bitbIt function to draw the star. Instead, it re-codes 
the whole function in TMS340 assembly language. This function requires 
the most effort form the application programmer to produce. Not every ex¬ 
tension should use this approach, but there is a well-defined route that al¬ 
lows an easy progression from host alone, through the simpler approaches 
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of C-packet and direct mode, to the custom assembly function. The custom 
assembly function allows a programmerto develop applications quickly, op¬ 
timizing time-critical functions to the limit. 

4.8.1.1 Generating the Downloadable Extension File 

The extension consists of the files containing the three downloaded subrou¬ 
tines, a data file containing the star shapes, and a special file containing the 
TIGAEXT section (starsgsp). The latter declares the list of downloaded 
functions to be installed in a specific order so that they can be referenced 
later. The order in which the functions appear in the TIGAEXT section define 
the command numbers used when the functions get invoked thus: 
draw_star_cp has a Command number of 0, draw_star_dm has a com¬ 
mand number of 1, and draw_star_asm has a command number of 2. All 
these files are linked together using the TMS340 linker (in the make file) with 
the -cr and -r options.This produces the relocatable load module 
starsgsp. rim. Note that in building the rim file the linker produces the mes¬ 
sage » warning: entry point symboi _c_int00 undefined. This can be 
ignored. 

4.8.1.2 Installing the Downloadable Extension File 

The initialization routine of stars. c performs the installation of the rim file 
by calling install_rlm. If the call to instail_rlm returns a negative result, an 
error occured; if it returns a positive number or zero, it is the module number 
of the installed group of functions. Every installed RLM receives its own 
module id. The first id is 0, the second id is1, etc. Because this application 
was invoked with set_videomode style of init, which initializes the heap, 
and as a by-product of this, deletes all extended primitives that were in¬ 
stalled, the application can be assured that the id of the first set of installed 
extensions is 0. Thus, the module identifier (mod_star) can be a constant 
0 in the program. 

The expected approach for the common mode of operation is that an appli¬ 
cation flushes out all extended primitives and downloads a single RLM file 
containing all its extensions. This approach has some minorspeed improve¬ 
ments over the more general approach where the module number is not 
known until runtime and the command number needs to be stored in a vari¬ 
able. 

Note that no directory is specified in the filename of the downloadable ex¬ 
tension. This is not a problem for a development environment because the 
current directory is the one searched first and the one where the extension 
is stored. In a production mode where different TIGA applications and driv¬ 
ers are stored in different directories, the user should set up a TIGA library 
directory that is pointed to by the -i field of the TIGA environment variable. 
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4.8.1.3 Invoking the Downloadable Extensions 

The three update cp, dm and asm functions are the ones that actually 
need to invoke the extensions. The extensions are invoked through the use 
of TIGA communication entry points; cp_cmd for the C-packet call and 
dm_cmd for the two direct-mode calls. To make the invocations more read¬ 
able, these calls are #defined to function calls that look like regular host 
functions. 

All the communication entry points take as a first parameter the command 
number of the TMS340 function to be invoked. The entry point consists of 
a function command number indicating the order in which the function ap¬ 
pears in the TIGAEXT section, ORed with the module number (which from 
the previous section is known to be 0 and so can be ignored). Following that 
are the commands parameters: 

1) C-Packet The number of packets, 4, followed by 4 word packets 
with parameters of the actual parameter data. The word macros build 
a packet containing the data size and type for the C-packet handler to 
interpret. 

2) Direct Mode The number of 16-bit words, 4, followed by four 16-bit 
words pushed onto the stack. 


4-39 



Example Programs 

S5SSa%s:5::*¥:%%:s:5SSWSSSSSft%:S!%%^%?WSS^^ 


4.8.2 Curves Example Program 


The curves example program draws a series of graphs of mathematical 
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ference is that it installs the extensions as separate modules. Thus, rather 
than assuming the module id is 0, the module id that is returned from the 
3 calls to instali_rim, is stored in the global variables moduie_draw_cp, 

_dm, _fp. 


The downloadable extensions are all passed an array of (x,y) coordinates 
which they draw. The points are produced by a generate_curve function, 
which involves a series of calls to a runtime support math function involving 
fioating point arithmetic. The final list of points are, for the C-packet and di¬ 
rect-mode calls scaled, to screen coordinates. 


The _fp case is a bit different. It passes a list of floating point values which 
are scaled to the screen by the extension function. It illustrates how floating 
point values can be passed through TIGA. Currently TIGA does not support 
the passing of floating point parameters directly. The reason is not due to 
TIGA but to the fact that TI\/IS340 floating point numbers are notin IEEE for¬ 
mat (and require conversion to and from IEEE format). The floating point ex¬ 
tension contains the source code of IEEE format conversion routines, which 
can be used for this. The TMS340 floating point format will be available in 
IEEE format in the near future, and direct floating point support will then be 
put into TIGA. 


4.8.2.1 Speed Optimization of Paraiiei Processing 

The timing of the extensions is done in two ways: First, time is taken directly 
following the functions being invoked (without synchronization). This gives 
a much shorter time than the second set of timings, which are taken after 
a call to the synchronize function. In the first case the time measured is that 
taken by the host. Second is the time taken by both the host and the 
TMS340. The TMS340 is a coprocessor and can offload much of the graphi¬ 
cal processing from the host and do it much faster. However, the time saved 
by an application also depends on utilizing both processes in parallel. If the 
application is written so that the host is simply waiting for the TMS340 to 
complete, then little or no time may be saved. 

When the application can perform an operation, say the calculation of the 
next set of graphical drawing coordinates, while the TMS340 is drawing, is 
whent the best performance improvements are achieved. This is important 
when choosing the communication entry points to use. Entry points that re¬ 
turn values, such as cp_ret, cp_alt, dm_ret, dm_ptrx, etc. all cause the 
host to wait until the TMS340 is finished. If a downloadable extension, which 
takes a long time to execute, is to return status information, it is perhaps bet- 
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ter to split the function into two. One to do the drawing, the other to return 
the status. That way the host calling function can invoke the first function 
without waiting, then go on to perform some calculations that are not depen¬ 
dent upon the status, then call the status function some time later. This uti¬ 
lizes both processors more efficiently. 

4.8.2.2 Invoking Downloadable Extensions 

The invocation of the three downloadable extensions brings out some fur¬ 
ther points that were not covered by the stars example. Referring to the #de- 
fines for the communication entry points: 

□ C Packet: This illustrates the passing of pointers in C-packet mode. No¬ 
tice that the third parameter c is also used to determine the size of the 
second parameter b. This is a very typical case. Unless a pointer is 
pointing to afixed size structure, a parameter is needed to tell the calling 
function how big the array being passed really is. This parameter can 
be used to tell the communication driver how much to send. The value 
may require scaling, as in this case, c refers to the number of vertices 
being passed, but as each vertex is made up of two 16-bit coordinates 
(x, y), the number of WORDS to be sent is c*2. 

□ Direct ModeiThe direct-mode entry point dm_pcmd allows the trans¬ 
fer of combinations of immediate data and pointers. The parameters 
are: 

-1 number of immediate words being sent 

- a immediate word 

-1 number of pointers being sent 

- c*4 number of BYTES to be sent in the pointer 

- b (far) pointer to the data 

Note that the c parameter is not sent explicitly as an immediate word. 
This is because since it is used as a count for the pointer data b, it ap¬ 
pears in the communication buffer multiplied by 4. Because the down¬ 
loaded extension can recreate it by a simple shift there is no point in 
sending it down twice. Notice too that the size is sent in bytes not words 
as it is for C-packet. What ends up in the communication buffer is best 
seen by consulting the routine draw_curve_dm. 

□ Floating Point: Although the floating point uses a DOUBLE_PTR 
which looks as a TIG A macro, it is defined in the curves program. TIGA 
treats doubles (which are the only floating point parameters passed to 
routines, floats are always promoted to doubles) as an array of 4 un¬ 
signed 16-bit words. Consult the function draw_curve_fp to see how 
the conversion of floating point occurs. Although this example does not 
show it, the altdouble_ptr can return floating point values from TIGA 
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4.8.3 ADi Driver Example 

The ADI directory contains the source of an example driver for ADI release 

3.1 which works with AutoCAD release 9. There is no discussion on how to 
write an ADI driver, since this is fully covered in the ADI Driver Development 
Kit that can be obtained from AutoDESK Corp. The only details given here 
are regarding certain features of TIGA utilized in this driver. 

4.8.3.1 Installing an ALM 

The requirement for an ALM has been fuiiy discussed in Section 4.1.2. The 
main program (in file adi. c) makes a call to create_alm to create the ALM 
from the RLM that is shipped with the driver. Then a trial call to install_alm 
is made, to see if there will be any problems in installing the ALM (for exam¬ 
ple, not enough heap) later. Toward the end of the main program, a call is 
made to the initialize function in the adiasm.asm file, to turn the program 
into aterminate-and-stay-residenttask. Note that previously a call is made 
to set_videomode(PREVIOUS, to end the TIGA session and return the 
board to an IBM graphics mode, such as EGA. 

Later, when AutoCAD is invoked and a drawing is edited, AutoCAD makes 
a call to the pinit function (in adi.c). The pinit function calls 
set_videomode(TIGA, to start the TIGA environment and then calls 
install_alm to install the ALM. 

4.8.3.2 Linking the Extended Primitives with the User RLM 

There is no call to install_primitlves in the ADI driver; although, some of 
the extended primitives are used in the driver. These primitives are iinked 
in with the ADI driver primitives and are loaded simultaneously. Thus, in the 
adiext. asm file, references are made to TIGA extended functions such as 
drawjine, bitbIt, etc. These primitives are supplied in TIGA both as an 
RLM and in the form of a library that can be iinked. This iibrary is referenced 
when the ADI RLM is created (see adiext. cmd). 

The advantage of linking the extended primitives with a user load module 
is that only those functions that are needed by the application are included, 
freeing up valuable space in TMS340 memory. Also, the time to load the 
functions is reduced. However, since the extended primitives are being 
loaded into a user module, their command numbers need to be modified. 
This is why their definitions appear in a header file adiext. h and why the 
TIGA extended primitive definitions appear in a separate include file ex¬ 
tend, h rather than in tiga.h. This enables their command numbers to be 
changed without the need to edit the standard TIGA include files. 
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4.9 Installing Interrupts 

Interrupt service routines contained within a dynamic load module must be 
written as a function calied with no arguments; that is, the last instruction 
should be a RETS 0 instead of a RETI. This is because the TIGA graphics 
manager provides a general interrupt handler that invokes the interrupt rou¬ 
tines only if they are enabled. This handler performs the actual RETI instruc¬ 
tion to return from the interrupt. 

In addition, the handler also provides for chaining of multiple interrupt ser¬ 
vice routines on a single interrupt level. This is vital for the TMS340 proces¬ 
sor, which often has more than one display interrupt active. For instance, 
the graphics manager provides three interrupts to control a hardware emu¬ 
lated cursor, page flipping, and wait-scan, all using the display interrupt. 

The interrupt service routines must be installed into the general interrupt 
handler during the installation of a dynamic load module.The routines that 
are to become interrupt service routines must be written, compiled, and as¬ 
sembled. Aspecially named TIGAISR section must then be declared, identi¬ 
fying the name of each interrupt service routine and the level where it should 
be installed. The format of this section is explained in Section 4.2.2 on page 
4-5. During the download process, the information within this special sec¬ 
tion is used to chain interrupts into the TIGA interrupt handler, where each 
interrupt is assigned a priority level. The interrupt priority can be retrieved 
for each ISR declared in the TIGAISR section, after a successful installation, 
by performing a call to get_isr_priorities. This routine returns an interrupt 
priority foreach ISR in their order of declaration in the section. Each interrupt 
is also installed in adisabled state and must be explicitly enabled by the pro¬ 
grammer. 

The setjnterrupt function must be called to enable or disable a particular 
interrupt service routine. The interrupt level and the associated priority must 
be specified as arguments to this function. 

Note that it is possible for a downloaded extension to be executed from the 
host and, in turn, set the traps to its own server to avoid the overhead of the 
global interrupt handler in certain time-critical functions. However, care 
must be taken, especially in the display interrupt used by TIGA primitives 
such as the cursor functions. If equivalent support is not given to these func¬ 
tions, as provided by the globai interrupt handler, certain TIGA primitives 
may not execute correctly. 

Certain TMS340 boards provide external connection to the LINT1 and 
LINT2 TMS340 processor pins. In such cases, interrupt service routines 
can be written for them using the techniques outlined here. However, such 
techniques are clearly not portable across all TMS340 processor boards. 
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4.9.1 Clock Example of Using Interrupts 

This example displays a real-time anaiog clock on the TMS340 screen, 
which is updated by the use of the timer interrupt function instalied in the dis¬ 
play interrupt. 

The timer functions are trivial, as can be seen in the timer .asm file; they 
simply increase a count. There is an additional function get_time, which 
returns the value of the count to the host. Notice that the TIGAEXT section 
is included with the timer. Because this is an assembiy language program, 
there is no need to keep TIGAEXT separate. There is an additional TIGAISR 
section, that is similar to TIGAEXT but holds an interrupt level in addition. 

The instaiiation of the interrupt service routine (iSR) is exactiy the same as 
for a regular extension, except that directly after the call to install_rlm is a 
call to get_isr_priorities (see main program of clock.C ). These calls re¬ 
turn the priority value for each of the interrupt service routines installed. Note 
that this means that an array big enough to hold all these priorities must be 
declared prior to invoking get_isr_priorlties to hold the values that will be 
returned. In this example only one ISR is installed, so a single short variable 
will suffice. The priority is used in the call to setjnterrupt to enable the in¬ 
terrupt. It is required, since TIGA allows any number of ISRs on a given in¬ 
terrupt level; thus the priority is the mechanism for identifying individual 
ISRs. 

Following the call to getJsr_priorities is a call to setjnterrupt. This takes 
two parameters to identify the ISR (an interrupt level and a priority) and two 
parameters, which may be set; an enable/disable flag and a display line (the 
latter Is valid only for display interrupts and is ignored by interrupts at other 
levels). 

After the interrupt is enabled, no direct reference is made to it. The function 
getjime is used to return the value of the count and thus determine the 
elapsed time. The getjime function in this example is not #defined; there 
is no absolute requirement to do this, but it is also clear that the code is less 
readable because of it. 
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4.9.2 Ball Example Using Interrupts 

This example demonstrates many of the same features of the previous ex¬ 
ample with one major exception. The interrupt service routine performs 
some graphics operation (in the form of drawing a ball on the screen). Be¬ 
cause the graphics operation uses implied operands in the B-file and I/O 
registers that cannot be guaranteed to be correct (since the interrupted rou¬ 
tine could be using the OFFSET or DPTCH B-file registers as temporaries), 
the interrupt service routine has to set up these values. Because this in¬ 
volves over-writing their current values, they must first be saved some¬ 
where. In this example they are saved in a global structure, by the routine 
setup_gsp_env. In an actual application, the registers could be pushed onto 
the stack using an MMTM instruction, if this function were recoded in 
TMS340 assembly. The graphics registers are then initialized using the val¬ 
ues from the global structures such as CONFIG. After the ISR has com¬ 
pleted, the restore_gsp_env function is called to restore the register values 
prior to returning to the interrupted function. 
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4.10 The TIGA Linking Loader 

The TIGA linking loader tigalnk is the mechanism by which extensibility 
is made possible. It is a full TMS340 linker that provides the capability of re¬ 
solving references to TIGA graphics manager (GM) functions, tigalnk is 
a full COFF loader which provides the capability of relocating object code 
anywhere in TMS340 memory. It is fully portable, using the TIGA communi¬ 
cation driver to interface to any TMS340 board that has TIGA ported to it. 
TIGALNK has extensibility control built into it, so that it can read the TIGAEXT 
and TIGAISR sections and inform the graphics manager of the user exten¬ 
sions that are to be installed. 

The linking loader is invoked by several TIGA primitives for installing exten¬ 
sions into TIGA, and for performing various other tasks. Applications and 
device drivers written for TIGA should restrict themselves to the TIGA primi¬ 
tives and never invoke the linking loader directly, as the linker is subject to 
change in future revisions of TIGA, while the procedural interfaces will re¬ 
main the same. A list of linking loaderflags with their procedural equivalents 
is given in the list below: 


Option Files 

Description 

Equivalent Function 

-ca 

RLMNAME,ALMNAME 

Link, then create an ALM 

create_aim 

~cs 

COFFNAME 

Create external symbol table 

create_esym 

-ec 

RLMNAME 

Check the RLM for errors 

none 

~fs 

SYMNAME 

Flush external symbol table 

flush_esym 

-la 

ALMNAME 

Load ALM into GM 

install_altn ^ 

-Ir 

RLMNAME 

Link, then load into GM 

install_rlm 

-lx 

COFFNAME 

Load and execute COFF file 

load_coff 

/gsp_execute 


TIGALNK can install an ALM. This is not done by the install_alm function, but by afunction 
in the communication driver. 


Below is a detailed description of the tigalnk options. Note that these op¬ 
tions can be placed anywhere on the command line; they do not have to be 
placed before filename arguments. 

In addition to the flags are a -q (quiet) option and a -v (verbose) option. If 
no options are specified, then the linker assumes normal command line op¬ 
eration and all working messages and error messages are displayed nor¬ 
mally. Selecting quiet mode operation suppresses all textual messages, 
and only error codes are returned upon termination (this mode is used in the 
procedural interface). In verbose mode operation, the linker provides mes¬ 
sages during every internal operation. 


4-47 



The TIGA Linking Loader 


4.10.1 /ca - Create Absolute Load Module 

This option creates an absolute load module (. alm) from the specified relo- 


J.I__ 


X__ .X A I 


eatable load module (. rlm). it tne narne ot tne output alm tiie is not speci¬ 
fied on the command line, then the base name of the RLM file is used, but 
with a forced file extension of .alm. Also, if no path information is supplied 
for the output file, then it is placed in the path specified by the -i option of 
the TIGA environment variable. 


4.10.2 /cs - Create External Symbol Table 

This option reads the symbolic information from the specified COFF file and 
places it in tiga 3 4 o. sym, or if the optional command line argument was spe¬ 
cified, in the Symbol filename soppWed. 


4.10.3 /ec - Error Check 

This command line option can be used to checkthe integrity of an RLM prior 
to installing it. The TIGA graphics manager does not have to be active in or¬ 
der for this option to work, but if it is, the largest amount of available heap 
that can be used to load RLMs is also displayed. 

Once executed, the /ec option scans the specified RLM and prints out the 
number of extensions or interrupt service routines contained within the mod¬ 
ule. If none are present, that is, no .TIGAEXT or .TIGAISR section is pres¬ 
ent, then a warning message is displayed. The amount of heap required to 
load the module is then displayed, and if the graphics manager is active, the 
largest available block of TMS340 heap is also displayed. 

If the module contains any unresolved references that would not be resolved 
at load time, these are printed out. This allows the user to resolved symbol 
references before actually attempting to download and install the file. 

I. . .. . ' ' ' ... ..1 

Note: 

Only symbols contained in the TIGA external symbol file (tiga 3 4 o. sym) are 
used to resolve symbol references. As supplied, or after creation by the /ix 
or /cs option, this file contains only the symbols for tigagm. out, the TIGA 
core primitives. If the module being checked contains references to other 
modules, such as the TIGA extended primitives, then these must be loaded 
prior to performing the check. 

» « 


Example: 


TI6ALNK /LX 
TIGALNK /LR extprims 



TIGALNK /EC user 


load and execute tigagm.out 
load TIGA extended primitives 
(extprims.rlm) 
check integrity of user. rim 


4-48 


Extensibility Through the User Library 




The TIGA Linking Loader 


4.10.4 /fs - Flush External Symbol Table 

This option flushes all but the symbols related to tigagm . out from the exter¬ 
nal symbol table, tiga340 . sym. As the symbols for each installed module 
are deleted, a call to the TIGA graphics manager is also made to delete the 
module from TMS340 memory. 

4.10.5 /la - Load and Install an Absolute Load Module 

This option loads and installs an ALM into the active TIGA graphics manager 
running on the target such that functions contained in the module can be in¬ 
voked from the host. 

I-1 

Note: 

ALMs contain no symbolic information, so modules loaded after an ALM 
cannot make references to symbols contained within an ALM. 


4.10.6 /ir - Load and Install a Relocatable Load Module 

This option loads and installs an RLM into the TIGA graphics manager so 
that functions contained in the module can be invoked from the host. 

Symbols contained in the module are added to tiga34o . sym, the external 
symbol table, so that they can be referenced by modules loaded afterwards. 

4.10.7 /lx - Load and Execute a COFF File / Execute TIGA GM 

This option has the ability to perform two distinct functions, depending on 
whether or not a COFF file is specified as a command line argument. If a 
COFF file name is provided on the command line, then it is loaded and ex¬ 
ecuted much like the stand-alone COFF loader provided with the Tl soft¬ 
ware development board. 

If a COFF file name is not provided, then it is assumed that the TIGA graph¬ 
ics manager is to be loaded and executed. In this case, two additional func¬ 
tions are performed after tigagm. out is loaded and executed. The TIGA ex¬ 
ternal symbol file (tiga340 . sym) is created, and the symbols contained in 
TIGAGM. OUT are written to it. Once complete, a call to the TIGA communica¬ 
tion driver function handshake is performed to initialize communications be¬ 
tween the host and the TMS340. 
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TIGA Data Structures 
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This appendix contains the data structures used in TIGA. They are defined 
in the include file typedef s .h. 


Section Page 

A.1 Integral Data Types.A-2 

A.2 CONFIG Structure.A-3 

A.3 CURSOR Structure.A-5 

A.4 ENVIRONMENT Structure .A-6 

A.5 FONTINFO Structure..A-7 

A.6 MODEINFO Structure.A-11 

A.7 MONITORINFO Structure.A-13 

A.8 OFFSCREEN Structure.A-14 

A.9 PAGE Structure.A-15 

A. 10 PALET Structure .A-16 

A. 11 PATTERN Structure. A-17 


The structure definitions supplied refer to the C syntax. In the assembly lan¬ 
guage equivalent file, typedef s. inc, the structure name precedes every 
field name. Thus, the hot x field In the cursor structure becomes cur- 
sor_hot_x . This is because in the macro assembler all fields must be 
unique. Note that this also applies to the TMS340 side equivalent file 
gsptypes. inc. This file also has all type definitions in uppercase. The two 
TMS340 side type definition files gsptypes .h and gsptypes. inc contain 
additional type definitions internal to TIGA and are not generally of use to 
the applications programmer. 
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A.1 Integral Data Types 

The TIGA data structures use the following type definitions throughout: 


typedef 

typedef 

typedef 

typedef 

typedef 


unsigned char 
unsigned short 
unsigned long 
unsigned long 
uchar far 


uchar; 
ushort; 
ulong; 
PTR; 
*HPTR; 
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A.2 CONFIG structure 

This structure contains the configuration information. Part of this structure 
is the MODEiNFO structure defined in Section A.6, which describes the 
board configuration. If alternate configurations are availabie, they can be set 
using set_config. 

typedef struct 

{ 

ushort version_number; 

ulong coinm_buf f_size; 

ulong sys_flags; 

ulong device_rev; 

ushort num_modes; 

ushort current_mode; 

ulong prograin_mem_start ; 

ulong program_mem_end; 

ulong display_mem_start; 

ulong display_mem_end; 

ulong stack_size; 

ulong shared_mein_size; 

HPTR shared_host_addr; 

PTR shared_gsp_addr; 

MODEINFO mode; 

}CONFIG; 

The CONFIG structure consists of the following fieids: 

version_number TIGA revision number, assigned by Texas Instru¬ 

ments. 

coiran_buff_size Size, in bytes, of the communications buffer; appli¬ 
cation needs to ensure that the data sent does not 
overflow this buffer, for commands that do not check 
the size of the downloaded data. 

sys_f lags Bits 0 — 7 indicate FPUs (Floating Point Units) are 

present to be compatible with the TMS34020 copro¬ 
cessor ID codes. Bits 8 —15 are reserved. 

device_rev This function invokes the TMS340’s REV instruction 

and returns its result here. 

num_modes Number of extended modes, for boards that allow the 

switching between different display setups. 

current_mode Mode number corresponding to the current operating 
mode. 

program_mem_start Start address of program memory. 
program_mem_end End address of program memory. 
dispiaY_mem_start Start address of display memory. 
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display_mem_end 

stack_size 

share_mem_size 

share__host__addr 

share_gsp_addr 


End address of display memory. 

Default stack size; can be modified using gsp_minit. 

Size (in bytes) of shared memory that is available for 
the application to use. 

If share_size is nonzero, it is the start address in 
host memory of the shared memory: otherwise it is 
undefined. 

If share_size is nonzero, it is the start address in 
TMS340 memory of the shared memory; othenwise, it 
is undefined. 
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CURSOR Structure 

A.3 CURSOR Structure 

This structure defines the cursor shape parameter for the set_curs_shape 

function. 

typedef struct 

{ 

short hot_x; 
short hot__y; 
ushort width; 
ushort height; 
ushort pitch; 
ulong color; 
ushort mask_rop; 
ushort shape_rop; 

PTR data; 

}CURSOR; 

This structure consists of the following fields: 

hot_x Offset x-coordinate added to the top left corner of the 

cursor shape to define the pixel specified by the 

set_curs_xy. 

hot_y Offset y-coordinate added to the top ieft corner of the 

cursor shape to define the pixel specified by the 

set_curs_xy. 

width Width of the cursor shape in pixels. 

height Height of the cursor shape in pixeis. 

pitch Linear difference in the addresses of successive 

rows of the cursor shape (in bits). 

color Foreground coior index with which the cursor is 

drawn. 

mask rop Pixel processing operation used when applying the 

mask data to the background. This is normally speci¬ 
fied as AND. 

shape_rop Pixel processing operation used when drawing the 

shape of the cursor onto the screen. This is normally 
specified as OR or XOR. 

data Pointer to TMS340 memory containing two contigu¬ 

ous arrays of width by height.The first array is the 
mask data with Os where the cursor is iocated and 1 s 
elsewhere. The second array is the shape data, 
which has 1 s where the cursor is located and Os else¬ 
where. 
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A.4 ENVIRONMENT Structure 


The ENVIRONMENT structure contains the TIGA drawing environment 
global variables. 


typedef struct 
{ 

ulong xyorigin; 
ulong pensize; 

PTR patnaddr; 

PTR srcbm; 

PTR dstbm; 

unsigned long stylemask; 

}ENVIRONMENT; 

The ENVIRONMENT structure consists of the following fields: 


xyorigin 

pensize 

patnaddr 

srcbm 

dstbm 

stylemask 


Current drawing origin in y::x format set by set_draw_origin 
Current pen size arranged in y::x format, set by set_pensize 
TMS340 address of current pattern, set by set_patn 

TMS340 address of current source bitmap structure, set by 

set_srcbm 

TMS340 address of current destination bitmap structure, set 
by set_dstbm 

Current line style mask used by styledjine function 
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A.5 FONTINFO Structure 

The text rendering capabilities included as part of the TIGA extended primi¬ 
tives are very rich, providing the application writer with the ability to display 
everything from simple, fixed cell type text, such as that used by dumb termi¬ 
nals and EGA, VGA graphics adapters, to the desktop publishing type (Wysi¬ 
wyg) text, where the height and width of characters, along with the style and 
size can vary. 

The fonts used for text rendering are a collection of characters having a 
unique combination of height, width, style, and other attributes. The format 
of these fonts are unique to TIGA and are described in the following para¬ 
graphs: 

The characters within a font have an associated two-dimensional bitmap 
that defines the shape of the character. When the text is rendered. On bits 
(1 s) within a character bitmap are expanded to pixels in the active fore¬ 
ground color, as set by the set_fcolor function. Off bits (Os) are expanded 
pixels in the background color. The format of a font is defined by the follow¬ 
ing data structure: 


typedef struct 
{ 


short 

magic; 

/* 

TIGA Identifier 


long 

length; 

/* 

length of font in bytes 


char 

facename[32] 

; 



short 

first; 

/* 

ASCII code of first character 


short 

last; 

/* 

ASCII code of last character 


short 

maxwide; 


maximum character width 

*/ 

short 

maxkern; 

/* 

maximum character kerning amount 


short 

charwide; 

/■^ 

char, width (0 if proportional) 


short 

avgwide; 

/* 

average width of characters 


short 

charhigh; 

/* 

character height 


short 

ascent; 

/* 

ascent (how far above base line) 


short 

descent; 

/* 

descent (how far below base line) 


short 

leading; 

/* 

leading (row bott.to next row top) 

*/ 

PTR 

fontptr; 


address of font in GSP memory 


short 

id; 

/* 

id of font (set at install time) 



}FONTINFO; 

The following is a description of the FONTINFO structure parameters. Pa¬ 
rameters 8, and 10 through 13 are shown in Figure A-1. 

1) magic 

This field is an identifier for the data structure. It consists of three parts: 
bits 00 — 01: data structure sub type 
bits 02 — 07: data structure type 
bits 08 —15: TIGA identifier 

For the bitmap fonts described here, the magic identifier is filled in as 
follows: 
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bits 00 — 01: 0 (FONT subtype = bitmap) 
bits 02 —07:1 (FONT) 

bits 0,8 —15: 0x80 (indicates TIGA font formatl .x) 

For this particuiar font data structure, the magic number vaiue is 
0x8040. in the future, TIGA may support outline or stroke fonts, in which 
case the font subtype would change. 

2) length 

The length of the entire font in bytes. This is useful when allocating 
memory for a font and for reading it from disk. 

3) facename 

A NULL terminated string of ASCII characters up to 32 long containing 
the name of the font. Example: Tl Roman, Tl Helvetica, etc. 

4) first 

ASCII code of the first character defined in the font. For example, if first 
was 0x20, the ASCII code for a space character, then that is the lowest 
ASCII code for which a bitmap is defined in the font. 

5) last 

ASCII code of the last character defined in the font. 

6) maxwide 

The width of the widest character defined in the font. 

7) maxkern 

The maximum kern for any character within the font, expressed as a 
positive value. For example, if kerning was 3, then the maximum any 
character will back up to overlap the previous drawn character is 3. 

8) charwide 

The character width is the image width of the character, plus the space 
separating this character from the next. If the character width is zero, 
then the width of characters within the font varies. In that case an entry in 
the offset/width table specifies the width for each character. 

9) avgwide 

The average width of characters within the font. This is the cell width of 
all defined characters within the font (not considering any kerning or ex¬ 
tra intercharacter spacing) divided by the number of characters defined. 
It is useful when selecting a font for a best fit at varying target resolu¬ 
tions. 
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10 ) charhigh 

The character height is the sum of the ascent and decent. It is constant 
throughout any particular font but may vary between fonts. 

11) ascent 

The ascent is the number of vertical pixels from the base line to the top of 
the font cell. 

12 ) descent 

The descent is the number of vertical pixels from the base line to the 
bottom of the cell. 

13) leading 

This term comes from the fact that typesetters often used strips of lead 
to adjust spacing between rows of characters when building a plate to 
be printed with a printing press. For bitmap fonts, this value is the num¬ 
ber of pixels recommended by the font designer that should be skipped 
between rows of characters, that is, if the leading is 3, then 3 pixels 
should be skipped between the descent line of a row of characters, and 
the ascent line of the row of characters drawn directly beneath. 
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Some of the fields in the font structure are illustrated in Figure A-1. The 
numbers refer to the numbered sections in the parameter description. 

Figure A-1. Bitmap Font Format 
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In addition, Figure A-1 illustrates the following font characteristics: 
a) Base Line 


The base iine is an invisible reference line corresponding to the bottom 
of the characters, not including the descenders. 

b) Character Origin 

The character origin isthatpartof acharactercorrespondingtoa speci¬ 
fied drawing location. This origin may vary, depending on the text align¬ 
ment attribute used to draw text. The defauit text alignment is relative to 
the top left corner of the character cell. Alignment can also be set rela¬ 
tive to the leftmost point on the character baseline by performing a call to 
set_textattr. Baseline origin is useful when a string of characters con¬ 
sists of different size or style fonts, in which case the baseline should 
remain constant throughout the text. 

c) Image Width 

The image width is the numberof bits of the portion of the character pat¬ 
tern bitmap containing the actual character image. This width does not 
include any blank space to the left or right of the character when it is 
displayed and can vary within a font and between fonts. 
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A.6 MODEINFO Structure 

This structure contains aii the configuration information that can vary on a 
specific board. It is part of the configuration structure returned by 
get_config (which returns oniy the MODEiNFO for the currentiy instaiied 
mode). The totai possible modes can be inquired using get_modeinfo. 

typedef struct 
{ 

ulong disp_pitch; 
ushort disp_vres; 
ushort disp_hres; 
short screen_wide; 
short screen_high 
ushort disp_psize; 
ulong pixel_mask; 
ushort palet_gun_depth 
ulong palet_size; 
short palet_inset; 
ushort nuin_pages; 
short num_of f scrn_areas; 
ulong wksp_addr; 
ulong wksp_pitch; 

}MODEINFO; 

The MODEINFO structure consists of the following fields: 

disp pitch Display pitch: linear difference between two scan 

lines in bits. 

disp vres Vertical resolution in scan lines. 

disp hres Horizontal resolution in pixels. 

screen_wide Contains the width of the monitor in centimeters. For 

systems where these dimensions are unknown, set 
to 1. 

screen_high Contains the height of the monitor in centimeters. For 

systems where these dimensions are unknown, set 
to 1. 

disp_psize Pixel size. 

pixei mask Contains a mask of the bits used in a pixel. It will nor¬ 

mally contain the value of 2 to the power dLsp psize 
minus 1, indicating that every bit of pixel data is perti¬ 
nent. On some boards, the frame buffer may be ar¬ 
ranged by 8 (disp_psize = 8) but with only 6 bits 
implemented. In that case, pixel mask would contain 
the value 63 (hexadecimal 3F). 

paiet_gun_depth Number of bits per gun in palette. 
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paiet_size Number of entries in the palette. 

paiet_inset For most systems, this field is set to 0. For 

TMS34Q7Q“b3S9d boards, which stors th6 p9!9tt9 in 
the frame buffer, this is the offset from the start of the 
scan line to the first pixel data. 

num_pages Number of display pages in multi-buffered systems. 

num_of f scrn_areas This is the number of offscreen memory blocks avail¬ 
able. If nonzero, theh it is used to allocate space for 
the offscreen array, ^hich can be obtained from the 
TMS340 via a call to the get_offscreen_memory 
function. 

wksp_addr Starting linear address in memory of offscreen work¬ 

space area. 

wksp_pitch Pitch of offscreen workspace area. If wksp_pitch = 

0 , then no offscreen workspace is currently allocated. 
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MONITORINFO Structure 


This Structure is not of general interest to an application writer. It is used by 
the OEM porting TIGA to its board to specify the values of the video timing 
parameters for a particular mode. Note that this structure is board-specific. 
An OEM is free to add to this structure its own OEM-specific video timing 
information. This structure will invariably change for a TMS34020 version 
of TIGA. 

typedef struct 
{ 

ushort hesync; 
ushort heblnk; 
ushort hsblnk; 
ushort htotal; 
ushort vesync; 
ushort veblnk; 
ushort vsblnk; 
ushort vtotal; 
ushort dpyctl; 
ushort screen_delay; 
ushort flags; 

}MONITORINFO; 

The MONITORINFO structure consists of the following fields: 

hesync value loaded into the HESYNC I/O register 

heblnk value loaded into the HEBLNK I/O register 

hsblnk value loaded into the HSBLNK I/O register 

htotal vaiue loaded into the HTOTAL I/O register 

vesync value loaded into the VESYNC I/O register 

veblnk value loaded into the VEBLNK I/O register 

vsblnk value loaded into the VSBLNK I/O register 

vtotal value loaded into the VTOTAL I/O register 

dpyctl value loaded into the DPYCTL I/O register 

screen_deiay NumberofframesthattheScreenisbiankwhenloadingthe 
video registers. This allows a monitor time to synchronize 
to the new timing before the screen is unblanked. 

flags Monitordesriptionflags.CurrentfiagsdefinedareO=color 

monitor, 1 = monochrome monitor. 
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A.8 OFFSCREEN Structure 

This structure defines the offscreen areas returned by the 
y6t_off3crG6ri___iTi6iTiory function. 

typedef struct 
{ 

PTR addr; 
ushort xext; 
ushort yext; 

}OFFSCREEN_AREA/ 

The OFFSCREEN structure consists of the following fields: 
addr Address in TMS340 memory of an offscreen work area, 
xext X extension of the offscreen area in the current screen pixel size, 
yext y extension of the offscreen area in the current screen pixel size. 
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A.9 PAGE Structure 

This structure is not of general interest to an application writer. It is used by 
the OEM porting TIGA to his board to specify the start addresses of the dis¬ 
play page (the value loaded into the display start I/O Register) and drawing 
page (the value loaded into the offset B-file register). This structure is used 
to support multiple display pages used by the page_flip function. Note that 
this structure is board-specific and may change in future versions of TIGA. 

typedef struct 
{ 

PTR BaseAddr 
ushort DpyStart 
short DummyPad; 

}PAGE; 

The PAGE structure consists of the following fields: 

BaseAddr Baseaddressof Start of drawing page; this value is loaded into 
the OFFSET B-file register. 

DpyStart Base address of start of display page; this value is loaded into 
the Display Start I/O register. 

DummyPad 16 bits to pad Structure to power of 2 size. 
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A.10 PALET Structure 

This structure contains the red, green, blue, and intensity components for 
a paiette entry. 

typedef struct 
{ 

uchar r; 
uchar g; 
uchar b; 
uchar i; 

}PALET; 

This structure consists of the following fields of the palette entry: 
r Value of the red gun 
g Value of the green gun 
b Value of the blue gun 

i Value of the intensity 
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A.11 PATTERN Structure 

The PATTERN structure defines the pattern shape information passed to 
the set_patn function. 

typedef structure 
{ 

ushort width; 
ushort height; 
ushort depth; 

PTR data; 

} PATTERN; 

This structure consists of the following fields: 

width Width of the pattern in bits. 

height Height of pattern in bits. 

depth Depth (bits/pixel) of pattern. 

data Pointer to pattern data in TMS340 memory. 


A-17 



A-18 


TIGA Data Structures 




Appendix B 


Graphics Output Primitives 


This appendix describes some of the assumptions made in the design of 
the TIGA graphics output primitives which are part of the extended primi¬ 
tives. It also describes the conventions adopted regarding the drawing, 
mapping, and filling with pixels to represent mathematical functions on a vid¬ 
eo screen. This appendix includes the following sections: 


Section Page 

B.1 Categories of Graphics Output Primitives. B-2 

B.2 Fill Patterns.B-4 

B.3 Mapping Pixels to XY Coordinates . B-5 

B.4 Area Filling Conventions. B-6 

B.5 Vector Drawing Conventions.B-7 

B.6 Drawing Pen .B-8 

B.7 Color Selection . B-9 
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B.1 Categories of Graphics Output Primitives 


The graphics functions draw several shapes in a variety of styles. Table B-1 
describes the figure types and drawing styles. Table B-2 shows the shapes 
that can be drawn in a particular style. The column headers list the available 
styles and the row headers list the available shapes; a check mark indicates 
that a shape can be drawn with a particular style. 


Table B-1. List of Function Types and Drawing Styles 


Function Types 

Function 

Name 

Description 

line 

A straight line. 

oval 

Ellipse in standard position (major and minor axes parallel to coordinate 
axes). 

ovalarc 

An arc of an ellipse in standard position, specified in terms of beginning and 
ending angles. 

point 

A single pixel or pen image drawn at the indicated XY coordinate pair. 

polygon 

A filled region defined by a collection of straight edges. Both convex 
polygons and arbitrarily complex polygons are supported. 

polyline 

A collection of straight lines. Figures made up of many lines can be drawn 
more efficiently by using the polyline commands than by repeated calls to 
the line functions. 

piearc 

Pie arc or wedge. Similar to ovalarc, but with addition of sides drawn from 
center of ellipse to arc endpoints to produce a closed figure. 

rect 

Rectangle with vertical and horizontal sides. 

seed 

Fill connected set of pixels beginning at specified seed point. 
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Drawing Styles 

Function 

Name 

Description 

draw 

Draws figure outline one pixel wide using background color. 

fill 

Draws figure interior filled in solid background color. 

frame 

Draws frame in solid background color. Horizontal and vertical 
thicknesses of frame border are both specified. 

patnframe 

Draws frame, using pattern in the foreground and background colors. 
Horizontal and vertical thicknesses of frame border are both specified. The 
pattern is programmable. 

patnpen 

Draws figure outline using pen and pattern in the foreground and 
background colors. Pen size and pattern are programmable. 

pen 

Draws figure outline using pen in solid background color. Pen is 
rectangular with programmable height and width. 

patnfill 

Draws figure interior filled with pattern in the foreground and background 
colors. The pattern is programmable. 


Table B--2, Checklist of Available Figure Types and Drawing Styles 



Drawing Sfj 

/les 

Figure 

Type 

draw 

pen 

patnpen 

fill 

patnfill 

frame 

patnframe 

line 

V 

V 

V 

N/A 

N/A 

N/A 

N/A 

oval 

V 



V 

V 

v 

V 

ovaiarc 

V 

V 

V 






V 

V 

V 

V 

V 




V 

V 

V 

N/A 

N/A 

N/A 

N/A 


N/A 

N/A 

N/A 

V 

V 

N/A 

N/A 


V 

V 

V 

N/A 

N/A 

N/A 

N/A 

rectangle 

V 



^/ 

V 

V 

V 

seed 

N/A 

N/A 

N/A 

V 

V 

N/A 

N/A 
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B.2 Fill Patterns 


Graphics functions that include patn as part of their names draw with a pat- 
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map and is represented in memory as an array of 256 contiguous bits. The 
bits in a pattern are listed in left-to-right order within a row, and rows are 
iisted in top-to-bottom order. 


Figure B-1 shows an example of a pattern as it appears on the screen. The 
smaii squares represent individual bits in the pattern; shaded squares rep¬ 
resent 1s, and white squares represent Os. The bit at the top left corner is 
the first bit (bit 0) in the pattern array. The bit at the iower right hand is the 
last bit (bit 255) in the array. 


Figure B-1. A 16 x 16 Pattern 



When a pattern is drawn to the screen, the Os in the bit map are replaced 
with the background color, and the 1 s in the bit map are repiaced with fore¬ 
ground coior. The pattern is mapped into 16 x 16 celis on the screen. The 
X and Y coordinates at the top ieft corner of each cell are both multiples. 
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B.3 Mapping Pixels to XY Coordinates 

Figure B-2 illustrates the conventions that are used to map XY coordinates 
to pixels on the screen. The filled area is a rectangle of width w = 5 and 
height = 3, whose top left corner is located at XY coordinates (4,2). The fill 
is performed by the following function call: 

fill_rect(5/ 3, 4, 2) 

Pixels lying within the perimeter of the specified rectangle are turned on to 
represent the fill area. By convention, X increases from left to right, and Y 
increases from top to bottom. The default drawing origin is at the upper left 
corner of the screen. (The origin may be relocated at an arbitrary position 
on or off screen with a call to the set_draw_origin function.) The XY coordi¬ 
nates passed to graphics routines are constrained to be integer values. The 
coordinate grid is overlayed on the screen so that integer XY coordinate 
pairs coincide with pixel corners (not with pixel centers). The conventions 
used for determining which pixels are selected to represent filled areas and 
infinitely thin vectors are explained in the foliowing sections. 


Figure B-2. Rectangle Fill 
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BA Area Filling Conventions 

Figure B-3 shows a filled polygon, in which a fill_polygon function defines 
the fiii area indicated by the straight edges in the figure. The rule for deter¬ 
mining whether a pixel is selected as part of the fill area is as follows: if the 
center of the pixel falls within the mathematical boundary of the area, it is 
turned on to indicate that is part of the fill area. (If a pixel’s center falls pre¬ 
cisely on the boundary between two areas, by convention the pixel is consid¬ 
ered to be part of the area immediately below and to the right of the pixel). 
Pixels whose centers lie outside the boundary are not considered part of the 
fill region. The same principles are applied to the filling of other shapes (el¬ 
lipses and thick lines drawn with a rectangular drawing pen, for example). 

Graphics functions that follow the above conventions for filled areas are all 
functions whose names include the modifiers fill, pen, or frame. 


Figure B-3. Polygon Fill 
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B.5 Vector Drawing Conventions 

Points, lines, and arcs are defined mathematically to be infinitely thin. Be¬ 
cause these figures contain no area, they are invisibie if drawn using the 
conventions for filled areas. A different set of conventions must be used to 
make points, lines, and arcs visible. These are the vector drawing conven¬ 
tions (to distinguish them from the area filiing conventions). Vector drawing 
conventions apply to all functions whose names include the modifier draw. 

The vector drawing conventions associate the point identified by the integer 
coordinate pair (X,Y) with the pixel located to its lower right; that is, the pixel 
whose center is located at coordinates (X+1/2,Y+1/2). For example, the 
draw_point (7, lO) command turns on the pixel at (7.5,10.5). As a second 
example, the polygon from Figure B-3 is shown again in Figure B-4 but is 
outlined rather than filled. (The draw_polyline function is used.) The points 
seiected to represent the right side of the polygon are indicated as small 
black dots. The pixel to the lower right of each point is turned on to represent 
the edge of the polygon. 

A line or arc drawn using the vector drawing conventions consists of a con¬ 
nected set of pixels. This means that the line or arc is drawn as a continuous 
set of pixels that connect (or touch) horizontally, vertically, or diagonally, 
without gaps or holes in between. 

Figure B-4. Polygon Outline 
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B.6 Drawing Pen 

The drawing commands that use vector drawing conventions can draw oniy 
pixel thick lines and arcs. To draw lines and curves of arbitrary thickness, 
a rectangular pen (or brush or logical pixel) is used. Graphics functions that 
use the drawing pen have names containing the modifier pen. 

The graphics commands can be used to set the drawing pen’s height and 
width to arbitrary positive, nonzero values. The pen is rectangular, and its 
position is identified by its top left corner. For example, when a pen of width 
w and height h draws a point at {X,Y), the resulting rectangle’s top left cor¬ 
ner lies at (X,Y), and its bottom right corner lies at (X+w, Y+h). The rectangu¬ 
lar area covered by the pen is filled either with a solid color or with the current 
pattern, depending on the function used. 

The area under the drawing pen is filled according to the area-filling conven¬ 
tions described previously. When the width and height of the drawing pen 
both equal 1, a line or arc drawn by the pen is similar in appearance to that 
drawn by a function following the vector drawing conventions. However, the 
pen functions conform to the area-filling conventions, so a pen function can 
track more faithfully the perimeter of a filled area than a corresponding draw 
function. 

For example, consider an ellipse defined by some width w, height h, and 
coordinates (x, y). If a draw_oval(w, h, x, y) function call outlines afilled el¬ 
lipse drawn by a fill_oval(w, h, x, y) function, the draw_oval function may 
not in all instances select the same perimeter pixels as the filled ellipse. This 
can leave gaps between the filled area and the outline. In contrast, a 
pen_oval(w, h, x, y) function call follows the filled ellipse precisely, remain¬ 
ing flush to the ellipse at al! points along the perimeter. 
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B.7 Color Selection 

The TIGA standard enables applications to be ported from one TMS340 
board to another. One of the most difficult parts of the porting process is en¬ 
suring that the colors chosen for the application are distinguishable (if not 
identical) when the application is run on another board. Palettes vary from 
board to board, sometimes considerably. This section describes the TIGA 
methodology concerning color selection. 

The configuration structure returned in get_config, contains the 
disp_psize element, which the application can use to determine the num¬ 
ber of colors that can be on the screen at any given time. The application 
must interrogate this value to determine if this number is sufficient, and 
double-up if necessary, painting different geometries with the same color. 

Selecting the colors is done via the set_palet, or set_palet_entry functions 
for a RAM-based palette. Because the palette may be ROM-based (making 
it impossible to set the palette entries), the functionjmplemented func¬ 
tion should be used on the set_palet functions prior to invoking them. If they 
are not implemented, the palette can be assumed to be ROM-based and a 
technique described later can be used to select colors. For RAM-based pa- 
lets, each entry can be set via a call to set_palet, which takes as its parame¬ 
ters an 8-bit value of red, green, blue, and intensity. 

For color monitors, the intensity field is ignored and the R-G-B values are 
used to load the palette entry. Because the palette may only use 4 or 6 bits, 
it takes the most significant portion of the 8-bit palette entry to set the color. 
The number of bits for each color gun is stored in the paiet_gun_depth 
field of the CONFIG structure. Alternatively, the get_palet function will re¬ 
turn the physical colors stored in each entry (as opposed to the logical colors 
requested by the set_palet function) .Thus, colors can be chosen and speci¬ 
fied directly with this approach. For monochrome monitors, only the intensi¬ 
ty field is used, to specify the level of the grey scale for each entry. Again, 
the most significant bits are used when the palette entry size is less than 8 
bits. Thus, for RAM-based palettes, the application should specify both a 
color and monochrome values for each color index used. 

For ROM-based palettes, the get_nearest_color function can be used to 
inquire which color index to use. This function operates in reverse to the pre¬ 
vious case where instead of setting an 8-bit red, green, blue color index with 
a desired value, the nearest one to the desired value is returned to the call¬ 
ing application. Again, an independent grey-scale value for each color index 
must also be requested for ROM-based monochrome monitors. 

In summary, the application must test functionjmplemented on set_pa- 
let to determine whether the palette is ROM- or RAM-based. If it is 
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RAM-based, the application can select its palette directly and must do so 
in both R-G-B and intensity values for monochrome monitors. If the palette 
is ROM-based, the application must use get_nearest_color on each of its 
desired palette entries to set up the color indices, again specifying both color 
and monochrome values. 

Finally, there is also a short cut: if the init_palet function is implemented 
(which is the case in RAM-based palettes with 4 bits-per-pixei or more), the 
palette values after initialization are those stated in the init_palet function. 
The palette values are declared symbolically in an insert file tiga .h, and 
if these values are acceptable, they can be used directly by an application. 
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C.1 Reserved Functions 

TIGA currently reserves the following functions for internal use. Do not 
chose function names that conflict with these. Avoid calling functions from 
an application program, since future versions of TIGA may not contain these 
functions. 

addjnterrupt 

add_module 

deLalLmodules 

deijnterrupt 

del_module 

get_memseg 

get_module 

get_msg 

get_state 

get_xstate 

gmjs_alive 

handshake 

init_cursor 

initjnterrupts 

init_video_regs 

makename 

oemjnit 

read_hstaddr 

read_hstadrh 

read_hstadrl 

read_hstctl 

read_hstdata 

rstr_commstate 

save_commstate 

set_memseg 

set_msg 

set_xstate 

write_hstaddr 

write_hstadrh 

write_hstadrl 

write_hstctl 

write hstdata 
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C.2 TIGA Core Primitive Symbois 

TIGA currently uses the following symbols in its core primitives and for the 
TMS340 C environment. To guarantee succesful operation, do not use 
downloadable extensions that conflict with any of these symbols. 

If the extension is also to work with the extended primitives, then Section 
C.3 should also be considered when selecting symbol names. 


.bss 

.data 

.text 

IsrCStk 

IsrEntryTable 

IsrSrv 

_CoreFunc 

_CursorlSR 

_DEFAULT_PALET 

_DefaultCursor 

_DiTable 

_Module 

_NextDiEntry 

_PageFliplSR 

_Trap Vector 

_WaitScanlSR 

_abort 

_addjnterrupt 

_add_module 

_atexit 

_bottom_of_stack 

_c_int00 

_check_dpyint 

_clear_frame_buffer 

_clearj)age 

_clear_screen 

_comm_info 

_config 

_cpacket 

_cpw 

_default_setup 
_del_all_modules 
_deljnterrupt 
del module 


delay 

dm_clear_frame_buffer 

dm_clear_page 

_dm_clear_screen 

dm_cpw 

d m_get_nearest_co lor 

dm_getjDalet 

dm_gsp2gsp 

dm_init_palet 

dmjmo 

dmj5eek_breg 

dmjDoke_breg 

dm_rmo 

_dm_set_bcolor 

dm_set_clip_rect 

dm_set_colors 

dm_set_cu rs_s hape 

dm_set_cu rs_state 

dm_set_fcolor 

_dm_setjDalet_entry 

dm_set_pmask 

dm_setjDpop 

_dm_set_windowing 

dm_set_wksp 

end_of_dram 

_envcurs 

envtext 

_env 

.exit 

_flush_extended 

.functionjmplemented 

_get_colors 

.get_config 
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_jget_curs_state 

^et_curs_xy 

_get_fontinfo 

_get_isr_priorities 

_get_module 

_get_nearest_color 

_jget_offscreen_memory 

_getjDalet_entry 

_get_palet 

_get_pmask 

_getjDpop 

_jget_state 

_get_transp 

_jget_vector 

_get_windowing 

_get_wksp 

_getrev 

_gsp2gsp 

^sp_calloc 

_jgsp_free 

_ 5 sp_malloc 

_jgsp_maxheap 

_gsp_minit 

_gsp_realloc 

JIlop 

_init_cursor 

JnitJnterrupts 

_init_palet 

Jnit_text 

_init_trap_vectors 

_init_video_regs 

Jmo 

_main 

_modeinfo 

_monitorinfo 

_offscreen 

_page_busy 

jDageJIip 

_page 


jDalet 

_palloc 

_j)attern 

_peek_breg 

jDoke_breg 

jDut_vector 

_release_buffer 

_rmo 

_set_bcolor 

_set_clip_rect 

_set_colors 

_set_config 

_set_curs_shape 

_set_curs_state 

_set_fcolor 

_setjnterrupt 

_set_palet 

_set_palet_entry 

_set_pmask 

_set_ppop 

_set_windowing 

_set_wksp 

_setup 

_stack_size 

_start_of_dram 

_strcpy 

_sys_free 

_sys_memory 

_sysfont 

_text_out 

_transp_off 

_transp_on 

_video_enable 

_wait_scan 

cinit 

edata 

end 

etext 
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C.3 TIGA Extended Primitive Symbols 

TlGA currently uses the following symbols in its extended primitives. Down¬ 
loadable extensions that work with the extended primitives should not use 
names that conflict with any of these symbols; this guarantee successful op¬ 
eration. 


_arc_draw 

_dmjDatnpenjDolyline 

_onarc 

_arc_fill 

_dm_pen_line 

_patn_line 

_arc_pen 

_dm_pen_ovalarc 

_patnfill_convex 

_arc_quadrant 

_dm_pen_piearc 

_patnfill_ovai 

_arc_quad 

_dm_penjDoint 

_patnfilljDiearc 

arc slice 

_dm_penjDolyline 

_patnfilljDolygon 

_bitblt 

_dm_seed_fill 

_patnfill_rect 

_cjnt00 

_dm_seed_patnfill 

_patnframe_oval 

_config 

_dm_set_draw_origin 

_patnframe_rect 

_delete_font 

_dm_set_patn 

_patnpenjine 

_dm_bitblt 

_dm_set_pensize 

_patnpen_ovalarc 

_dm_draw_line 

_dm_zoom_rect 

jDatnpenjDiearc 

_dm_draw_oval 

_draw_eliparc 

jDatnpenjDoint 

_dm_draw_ovalarc 

_draw_line 

_patnpen_polyline 

_dm_drawjDiearc 

_draw_ovalarc 

_pattern 

_dm_draw_point 

_draw_oval 

_pen_eliparc 

_dm_drawjDolyline 

_draw_piearc 

_penjine 

_dm_draw_rect 

_drawjDoint 

_pen_ovalarc 

_dm_fill_convex 

_draw_polyline 

jDenjjiearc 

_dm_fill_oval 

_draw_rect 

jDenjaoint 

_dm_fill_piearc 

_env 

_pen_polyline 

_dm_fill_polygon 

_envtext 

_seed_fill 

_dm_fill_rect 

_fill_convex 

_seed_patnfill 

_dm_frame_oval 

_fill_eliparc 

_select_font 

_dm_frame_rect 

_fill_oval 

_set_draw_origin 

_dm_get_pixel 

_fill_piearc 

_set_dstbm 

_dm_patnfill_convex 

_fill_polygon 

_set_patn 

_dm_patnfill_oval 

_fill_rect 

_setjDensize 

_dm_patnfilljDiearc 

_fill_shape 

_set_srcbm 

_dmjDatnfillj3olygon 

_frame_oval 

_set_textattr 

_dm_patnfill_rect 

_frame_rect 

_sin_tbl 

_dm_patnframe_oval 

_jget_env 

_styled_line 

_dm_patnframe_rect 

_get_pixel 

_swap_bni 

_dm_patnpenjine 

_get_textattr 

_sysfont 

_dm_patnpen_ovalarc 

_gsp_malloc 

_text_width 

_dm_patnpenjDiearc 

_gsp_realloc 

_zoom_rect 

_dm_patnpen_point 

_install_font 
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Porting TIGA 


The TIGA-340 Software Porting Kit (SPK) contains ail source required to 
port TIGA to any TMS340-based graphics board. The SPK is originally 
shipped with a Tl Software Development Board (SDB) compatible version 
of TIGA. This version is used as an example, and a port of TIGA to a different 
TMS340 board will involve modifications to the SDB port. 

Before beginning the porting process, make sure you have the following 
software tools installed on your system: 

□ Microsoft macro assembler, version 5.0 or above 

□ Microsoft MAKE utility 
□i Microsoft linker 

□ TMS340 assembler/linker, version 3.0 or above 

□ TMS340 C compiler, version 3.0 or above 

Porting TIGA consists basically of two tasks.The first is to modify the 
host-side TIGA code (the TIGA communication driver or CD for short). The 
second is to modify the TMS340-side code (the TIGA graphics manager or 
GM for short). Each of these tasks have well-defined, step-by-step proce¬ 
dures that make porting TIGA to a different TMS340-based board a relative¬ 
ly simple operation. Because the GM rebuilding process relies on afunction¬ 
al CD, you must first port the CD before porting the GM. 

Porting TIGA entails some knowledge of TlGA’s architecture; therefore, it 
may be helpful to refer to Section 1.3 for an overview of the components of 
TIGA. 


Section Page 

D.1 Porting the Communication Driver (CD).D-2 

D.2 Porting the Graphics Manager.D-14 

D.3 Verifying Correct Operation .D-21 

D.4 Debugging Your Port.D-22 
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D.1 Porting the Communication Driver 

The TIGA communication driver (CD) is an MS-DOS Termi- 
nate-and-Stay-Resident (TSR) program that enables host communications 
with the TMS340-based board. When the TIGA-340 SPK is installed, it 
places all CD-specific files in the directory \tiga\cd. The files within this di¬ 
rectory that may need modifications, along with a description of each, are 
listed below: 

oemdata.asm Contains information defining each mode of operation 
supported by the TMS340-based board 

oeminit. asm Contains board-specific initialization and inquiry functions 
setvideo. asm Contains routines to set/get video mode information 
sdbdef s. inc Contains hardware-specific equates 

Porting the TIGA CD involves modifications to each of the files above. The 
following four sections describe in detail these modifications. Note that all 
references to file names are assumed to be files within the \tiga\cd direc¬ 
tory unless otherwise noted. 

D.1.1 Modifying the sdbdef s • inc Fiie 

The sdbdef s. inc file Contains general information describing the hardware 
aspects of the target TMS340-based board TIGA is being ported to. Before 
making any modifications to this file, first copy it to a file that will be used to 
describe yourtarget board. Make sure to copy it within the \tiga\cd direc¬ 
tory and that its extension is . inc. For example purposes, assume the co¬ 
pied filename is newdef s. inc and use this filename throughout the commu¬ 
nication driver porting guide. 

Next, edit newdef s. inc; note that the file contains a number of equates de¬ 
fining constants that are used when the TIGA CD is rebuilt. Modify only 
the constants described below. Modifications to any constant not listed be¬ 
low will result in a non-functioning communication driver: 

OEMMSG This message is displayed when the CD is installed. It de¬ 
scribes the board on which TIGA is running. Be sure to en¬ 
close the description within double quotes. 

SDB If your target board is not the T1 Software Development Board 

(SDB), then set this constant to false (0). 

MEMORY This constant defines how the TMS340’s host registers 
(HSTDATA, HSTCTRL, HSTADRH, and HSTADRL) are ac¬ 
cessed from the host. If your target board’s host registers are 
memory-mapped, set this constant to 1. Otherwise, they are 
I/O-mapped, in which case the constant should be set to 0. 
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SYSTEM If you want your TIGA CD to be compatible with Intel’s 8086 
and later microprocessors, set this constant to false (0). If set 
to TRUE (1), 80x86 instructions will be used in the CD. This 
results in faster execution but places a restriction on the host 
processor type. 

Next, modify the host portion defining the host port locations. These equates 
define the host addresses (either memory or I/O) used to communicate with 
the TMS340. Note that these addresses are hard-coded. If your board can 
be configured to different host address memory locations, seiect one set of 
addresses for the initial port (referto section D.1.19 for more information on 
boards with multi-host port addressing). 

Note that the HSTSEG address is valid for memory-mapped host register 
boards only. Modify these constants to match your board’s host register ad¬ 
dressing. 

The foiiowing values for the host register addresses are taken from the SDB 
(memory-mapped) port. 


HSTSEG 

HSTADRL 

HSTADRH 

HSTDATA 

HSTCTRL 


Equ OCOOOh ; Host port seg. (mem-mapped only) 
Equ 7E00h ; Host address low 

Equ 7F00h ; Host address high 

Equ 7000h ; Host data 

Equ 7D00h ; Host control 


The next two equates are used as timeout values in the CD. For most ports, 
these values should suffice. However, if the call to gmjs_alive fails consis¬ 
tently, you may have to increase the GM_TIMEOUT vaiue (see Section 
D.1.18 for more information). 


The next set of constants defines various monitors supported by the differ¬ 
ent operating modes of your board. Each monitor constant defines a bit flag 
in a 16-bit word. Therefore, TIGA supports up to 16 monitors per mode. 
The foliowing monitor definitions were taken from the SDB port: 


NEC Equ 1 ; SDB port supports two monitors, the 

SONY Equ 2 ; NEC and the SONY Multisyncs 

Here, two monitors are supported, the NEC Multisync and Sony Multisync. 
Note that the first monitor constant has a vaiue of 01 h, and the next has a 
vaiue of 02h. If additional monitors were supported, their values would be 
04h, 08h, lOh, etc., up to 80h. 

Next, modify the number of palette entries supported on your board in its de¬ 
fault power-up mode. The SDB uses the TMS34070 4-bit color palette and, 
therefore, has 16 palette entries. 

Finally, one miscellaneous equate may need modification for your port. 

STKSIZE-The host-side communication driver stack size may be modified 
to suit your needs. The SDB port allocates 0400h bytes of stack. 
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D.1.2 Modifying the oemdata. asm Fiie 

The oemdata. asm file Contains descriptions of ali the operating modes sup¬ 
ported by your board. An operating mode is defined as a given resolution 
with appropriate monitor timing values that support this resolution. The op¬ 
erating modes of the SDB port are used as an example. Use this example 
as a guide to define the operating modes of your board. 

The label Setup_Table defines the start of the operating mode specific data. 
The SDB port supports four operating modes: the first is a 640 x 480 x 4 reso¬ 
lution mode (1 display page) and the second is a 448 x 480 x 4 (2 display 
pages) mode. These two modes are duplicated forthe NEC and Sony Multi¬ 
sync monitors. Each mode supported by your board must be defined by a 
label following the Setup_Entry label. These mode labels are used to actual¬ 
ly define the mode-specific data. 


; Define number of modes and mode/setup tables 


/ 

Setup_Table Equ This Word 
Setup_Entry Mode_640x480x4N 
Setup_Entry Mode_448x480x4N 
Setup_Entry Mode_640x480x48 
Setup_Entry Mode_448x480x4S 


; Start of setup table 
; SDB mode 0 for NEC 
; SDB mode 1 for NEC 
; SDB mode 0 for Sony. 
; SDB mode 1 for Sony. 


D.1.3 Defining the Mode-Specific Information 

Each board operating mode has its own set of data describing the following 
items: 

□ Monitor identification flags 

□ Mode-specific information 

□ Monitor timing information 

□ Display page information 

□ Offscreen memory information 

For example, mode 0 of the SDB port is defined as follows: 
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SDB Mode 0: 640x480x4, 1 
*************************1 


page for NEC Monitor 


SETUP Structure 


Mode_640x480x4N 
Setup_Struc 
Mode_Info 
Monitor_Info 
Page_Info 
Off_screen 
Off_Screen 
Off_Screen 
End_Setup 


Equ This Byte ; Mode 0 setup structure 

<NEC> 

1000h,480, 640,27,20,4, 0Fh,4,PALET_ENTRIES,lOOh,1,2,OBOOh,lOOOh 
OlBh, OlCh, OCCh, OCDh, OOlh, 018h, 01F8h, OlFAh, OFOlOh, 30, 0 
00000100h,0FFFCh 
OOOOOBOOh,640/4,480 
00000D80h,160,480 
OOlEOOOOh,1024,32 


Each operating mode of your board has a similar block of information de¬ 
fined, one block for eack mode defined in the Setup_Table. Use the follow¬ 
ing instructions to modify each mode information block for your board. 


D.1.4 Defining the Mode Label and Setup_Struc Structure 

The mode setup structure starts with a label identifying the mode. This label 
is the same as the one added in the Setup_Table entries earlier. 

Next, initialize the Setup_Struc macro with the valid monitors supported by 
this mode. These monitor constants were defined earlier in the 
newdef s. inc file. 


D.1.5 Defining the Mode_Struc Structure 

Next, modify the mode-specific information. The Mode_info structure con¬ 
tains parameters describing this operating mode. The structure is defined 
in the file struct. inc as follows: 


Mode_Struc 

Struc, 

Mode_Disp_Pitch 

Dd? 

; 

Mode_Disp_Vres 

Dw ? 

/ 

Mode_Disp_Hres 

Dw? 

/ 

Mode Screen Wide 

Dw? 

; 

Mode_Screen_High 

Dw ? 

/ 

Mode_Disp_Psize 

Dw ? 

; 

Mode_Pixel_Mask 

Dd? 

/ 

Mode_Palet_Gun_Depth 

Dw ? 

/ 

Mode Palet Size 

Dd? 

r 

Mode_Palet_Inset 

Dw ? 

r 

Mode Num Pages 

Dw? 

/ 

Mode___Num_Of f scrn 

Dw? 

r 

Mode_Wksp_Address 

Dd? 

r 

Mode_Wksp_Pitch 

Dd? 

r 

Mode Struc 

Ends 

/ 


Mode information structure 
Display pitch (bits) 

Vertical resolution (pixels) 
Horizontal resolution (pixels) 
Screen width (centimeters) 
Screen height (centimeters) 
Display pixel size 
Pixel mask 

Palette gun depth (bits) 
Palette size 

(For TMS34070 palette only) 
Number of screen pages 
Number of off-screen areas 
Temporary Workspace Address 
Temporary Workspace Pitch 
End of Mode Struc structure 


The Mode_Num_Pages field describes the total number of display pages 
supported for this mode. Multiple display pages are used in TIGA to support 
animation via the page_flip function. Section D.1.7 provides additional in¬ 
formation. 
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The Mode_Num_Offscrn field describes the total number of x-y offscreen 
memory blocks available for use by an application. Section D. 1.8 describes 
these memory blocks in greater detail. 

The fields Mode_Wksp_Address and Mode_Wksp_Pitch describe the off¬ 
screen workspace. This workspace is a 1 -bit-per-pixel bitmap with the same 
horizontal and vertical dimensions as the visible screen. It is used by the 
fill_polygon and patnfill_polygon functions as a working buffer. If enough 
offscreen memory is available to support this workspace, then this offscreen 
memory block should be the first Off_Screen structure defined (see Section 
D.1.8) and the Mode_Wksp_Address and Mode_Wksp_Pitch fields should 
be initialized to point to this block. 


D.1.6 Defining the Monitorjnfo Structure 

Next, modify the Monitorjnfo specific data for this mode. This structure is 
defined in the struct. inc header file as follows: 


Monitor_ 

_Struc 

Struc, 

Monitor_ 

Hesync 

Dw? 

/ 

Monitor 

"Heblnk 

Dw? 

r 

Monitor_ 

_Hsblnk 

Dw? 

/ 

Monitor 

_Htotal 

Dw? 

/ 

Monitor_ 

Vesync 

Dw? 

/ 

Monitor_ 

_Veblnk 

Dw? 

/ 

Monitor_ 

~Vsblnk 

Dw? 

; 

Monitor_ 

’Vtotal 

Dw? 

/ 

Monitor_ 

_Dpyctl 

Dw? 

/ 

Monitor_ 

_Screen_Delay 

Dw ? 

/ 

Monitor_ 

"Flags 

Dw? 

/ 

Monitor 

Struc 

Ends 

/ 


Monitor information structure 
End horizontal sync signal 
End horizontal blank signal 
Start horizontal blank signal 
Horizontal total (Characters) 
End vertical sync signal 
End vertical blank signal 
Start vertical blank signal 
Vertical total (Scanlines) 
Display control register 
Screen delay (Frames) 

Monitor type flags (BitO 
:0=color, l=mono) Bits 1-15 
reserved 

End of Monitor Struc structure 


The structure element, Monitor_Screen_Delay, specifies the delay (in 
frames) that the screen will be blanked when the video registers are loaded. 
This allows the monitor time to synchronize to the new timing values. 


The structure element Monitor_Flags specifies whether the monitor is color 
(when the LSB is a 0), or monochrome (when the LSB is 1). Bits 1 —15 are 
reserved. The palette routines use this flag to choose between the intensity 
level or the R, G, B values specified in the palette structure. 


D.1.7 Defining the Pagejnfo Structure 

The next structure, Pagejnfo, contains information defining the available 
display pages for this particular mode. Each mode must have at least 1 dis¬ 
play page defined. For each display page, a corresponding Pagejnfo 
structure must be defined. The actual number of display pages is defined 
in the Mode_Num_Pages field of the Mode_Struc structure. The Pagejnfo 
structure is defined in the file struct. inc as follows: 


D-6 


Porting TIGA 



Porting the Communication Driver 


Page_Struc 

Page_Base_Addr 

Struc 

Dd 

7 

; Page information structure 
; Page base address 

Page_DpyStart 

Dw 

7 

; (linear bit address) 

; Page start offset 

Page_Pad 

Dw 

7 

; Page dummy pad bytes 

Page_Struc 

Ends 


; End of Page_Struc structure 


Each page is defined by two elements: 


1) The base address (loaded into the B-file register OFFSET) when this 
page is being written to 

2) The display start (loaded into the DPYSTRT I/O register) when this 
page is being displayed 

Using Mode 1 (448 x 480 x 4,2 pages) of the SDB port as an example, two 
display pages are supported. These page definitions are as follows; 

Page_Info OOOOOlOOh,OFFFCh ; Page 0 

Page_Info 00000900h,0FFF4h ; Page 1 

The TIGA core function, page_flip, enables the selection of the current dis¬ 
play and drawing page. For example, page_flip(0,1) selects page 0 as the 
display page and page 1 as the drawing page. Therefore, B-file register 
OFFSET would be loaded with 0900h (the base address for page 1) and 
the DPYSTRT lO register with OFFFCh (the display start for page 0). 

I-1 

Note: 

Even though the Pagejnfo structure contains 16 bits of pad, this value 
should not be entered as part of the Pagejnfo information. 

I_1 


Be sure and note the maximum number of display pages defined in any op¬ 
erating mode of your board. This value is required when porting the TIGA 
graphics manager. 


D.1.8 Defining the Off_Screen Structure 

TIGA enables an application to use offscreen memory as a bitbIt storage or 
temporary workspace though the get_offscreen_memory function. This 
function returns information describing the available offscreen memory 
areas that are defined in the OFF SCREEN structure. 


The OFF SCREEN structure is defined in the file struct. inc as follows: 


Screen_Struc 
Screen_Address 
Screen_X_Ext 
Screen_Y_Ext 
Screen Struc 


Struc ; Screen information structure 
Dd ? ; Start (linear) off-screen memory 

Dw ? ; X extent of memory (pixels) 

Dw ? ; Y extent of memory (pixels) 

Ends ; End of Screen Struc structure 
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The actual number of offscreen areas for a particular mode is defined in the 
Mode_Num_Offscrn field of the Mode_Struc structure. For each offscreen 
area, a corresponding Off_Screen structure is defined. If your board does 
not contain any offscreen areas, then no off-screen structures need be de¬ 
fined. 

Using Mode 0 of the SDB port as an example, 3 offscreen memory areas 
are available and are defined as follows: 

Off_Screen OOOOOBOOh,640/4,480 ; Alloc.to offscrn wksp 0 
Of£_Screen OOOOODSOh,160,480 ; Offscreen area 1 

Off_Screen OOlEOOOOh,1024,32 ; Offscreen area 2 

Note that the first Off_Screen block defined is intended to be used for the 
offscreen workspace. The Mode_Wksp_Pitch and Mode_Wksp_Addrfields 
of the Modejnfo structure for ModeO are initialized to point to this block. 

Be sure and note the maximum number of offscreen areas defined in any 
operating mode of your board. This vaiuewiil be required later when porting 
the TIGA graphics manager. 

D.1.9 Defining OEM-Specific Data 

If you have any other mode-specific data, it should be added to the operat¬ 
ing mode data using the OEM_Data structure. This structure, defined in the 
macro.inc fiie, foilows the Off_Screen structure data. To use the 
OEM_Data structure, modify the number of parameters expected by the 
OEM_Data macro in the macro.inc fiie. Then, supply the OEM-specific 
data using the OEM_Data macro. A corresponding change is required in the 
graphics manager portion of TIGA to support this new data. 

I-1 

Note: 

In the SDB port, no OEM_Data is defined, but an example of its usage is 
shown. 


D.1.10 Completing Modifications to oemdata.asm 

Repeat the above instructions to define ail operating modes for your particu- 
iar board. 

After the last mode information block, global data variables used by the CD 
are declared. The Previous_Mode variable may require changing. This vari- 
abie is used to store the TMS340 board emulation mode (that is, EGA, VGA) 
prior to ioading TIGA. Because the SDB does not support emulations, the 
Previous_Mode is set to TIGA. However, if your board does support emuia- 
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tions, then initialize this variable to the emulation mode in which the board 
powers up. If the emulation is configurable by DIP switches, then an appro¬ 
priate function called within the oemjnit function (see Section D.1.11) 
should be written to initialize this variable. Valid constants for emulation 
modes are defined in the file \tiga\inciude\tiga .h file. 

Finally, the DRAM_Start and DRAM_End symbols need to be initialized to 
the largest block of DRAM on the target board. 

DRAM_End is used to store the high-water mark in memory where the sys¬ 
tem stack resides. The address should be double-word aligned and must 
not be higher than OFFFFDFEOh, since memory above this address is re¬ 
served in the TMS340 memory map. This address should also be equal to 
the bottom_of_stack value in the link control file of the graphics manager. 

D.1.11 Modifying the oeminit.asm Fiie 

The oeminit. asm file Contains functions used to initialize a specific 
TIGA-compatible TMS340 target board. The functions in oeminit.asm 
shipped with the TiGA Software Porting Kit perform specific initializations 
for the SDB and therefore require modifications for your particular board. 

The oeminit . asmfile Contains the following four board-specific initialization 
functions: 

OEMJnit Initializes the board. 

OEM_Sense Returns ID of current monitor in use. 

Monitorjnit Initializes the TIGA mode table with all valid modes for cur¬ 
rent monitor in use. 

Video_Enable Switches video from EGA/VGA to TIGA. 

D.1.12 Modifying the OEMJnit Function 

The OEMJnit function performs all initializations necessary to put the target 
TMS340-based board in a state where the TIGA graphics manager can be 
loaded to it. The TIGA communications driver calls the OEMJnit function 
when it is initially loaded. 

Using the SDB port as an example, the OEMJnit function first halts the 
TMS340, flushes the cache, and sets the INCR and INCW bits in the 
TMS340’s HSTCTL register. It then switches on the SDB’s shadow RAM, 
clears the interrupt enable I/O register so that the board TMS340 can be 
halted later, and clears the TMS340’s CONTROL register. 

Note the comment within the OEMJnit function regarding the setting of the 
CONTROL register. It is extremely important to initialize the CONTROL 
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register properly to support the type of DRAM refresh cycles used on the 
board. 

I-1 

Note: 

Do not modify the code related to the high-water mark. 

I_I 


D.1.13 Modifying the OEM_Sense Function 

The OEM_Sense function is used to return the ID of the monitor that is con¬ 
nected to the target TMS340-based board. The valid monitor IDs were pre¬ 
viously defined in the newdef s. inc file. 

In the SDB port, there is no way to sense the type of monitor using the SDB. 
However, on other boards, DIP switches or monitor sense lines are avail¬ 
able for this purpose. This example function searches for a -s command 
line argument and sets dx to the Sony id if found. Otherwise, dx is set to 
NEC. 

D.1.14 Modifying the Monitorjnit Function 

The monitorjnit function calls OEM_Sense to get the current monitor con¬ 
nected to the target TMS340-based board. It then steps through the list of 
all modes defined in the Setup_Struc structures (defined in oemdata. asm) 
and puts the indices of those modes that support the current monitor into 
space allocated in Mode_Table (defined in oemdata. asm). This, in essence, 
defines the total number of modes available for the current monitor in use. 

This function requires no modifications except when more than 16 monitors 
are supported. 

D.1.15 Modifying the Video_Enable Function 

This function invokes a graphics manager function that does nothing on the 
SDB, because there is no EGA emulation implemented on the SDB. Vid- 
eo_Enable is shown here as an example of its implementation. If the video 
on your board can be switched directly from the host side, then modify this 
function to do so. Otherwise, as illustrated In the SDB port, call the 
Video_Enable graphics manager function to perform the video switch. 

D.1.16 Modifying the setvideo. asm Fiie 

The two functions within setvideo. asm, set_videomode and 
get_videomode, require porting only for those TMS340-based boards 
which support other graphic modes (that is, EGA, VGA, etc.). Because the 
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SDB does not support any other graphics modes, comments are given with¬ 
in the setvideo.asia code to offer suggestions on alternative graphics 
mode support. 

D.1.17 Miscellaneous Communication Driver Porting Issues 

The following sections describe additional modifications that may be need¬ 
ed for porting the TIGA communications driver to your specific board. 

D.1.18 Default Timeout for gmjs_alive Function 

The file error. asm Contains the function gmjs_alive. The purpose of this 
function is to check if the TIGA graphics manager (the part of TIGA which 
runs on the TMS340-side) is alive and running. It does this by installing its 
own error trap, calling one of TIG As core primitives, and then waiting a cer¬ 
tain period for the TIGA primitive to complete. If the function does not com¬ 
plete in the time allotted, the error handler is called and false (0) is returned, 
indicating a non-functioning graphics manager. 

The delay time is defined by the constant GM_TIMEOUT in the file 
newdef s. inc and is Set in the SDB port to 0.5 seconds. This timeout value 
may have to be lengthened on those boards with monitor screen delays 
longer than 30 frames (see Defining the Monitorjnfo Structure in Section 
D.1.6). 

This potential problem is evident when an application calls a function requir¬ 
ing the use of TIGA’s linking loader TIGALNK (that is, create_alm) immedi¬ 
ately following a call to set_videomode(TIGA,INITIALIZE). Because the 
call to set_videomode reloads the video timing registers (using the delay 
defined by the monitor delay amount), and tigalnk first checks if the TIGA 
graphics manager is alive (via gm_is_alive), there is a chance that this 
delay will cause gm_is_alive to fail, tigalnk then returns an error mes¬ 
sage indicating that the ALM file could not be created (in this example). 

D.1.19 Using Boards with Muiti-Addressable Host Port Locations 

TMS340-based boards with multi-addressable host port locations were 
mentioned in Section D.1.1. Because the host port addresses are hard¬ 
coded in the newdef s. inc file. Only one of the address sets are supported. 
However, by making some simple modifications, programmable host port 
addressing is possible. 

First, five 16-bit variables must be declared in the CD data section (in the 
file data.asm). These variables are 

HstCtrlAdr dw ? ; HSTCTRL host address 
HstAdrlAdr dw ? ; HSTADRL host address 
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HstAdrhAdr dw ? ; HSTADRH host address 

HstDataAdr dw ? ; HSTDATA host address 

HstSegAdr dw ? ; Segment address (memory map only) 

Next, these addresses must be initialized before any i/O is performed 
through the TMS340’s host port. 

The file macro.inc Contains all the macros that perform I/O functions 
through the TMS340 host port. For example, Write_HSTDATA is a macro 
which writes 16 bits of data to the TMS340 HSTDATA register. For memory 
mapped boards, ax is assumed destroyed by these macros. For I/O- 
mapped boards, ax and dx are assumed destroyed. Currently, these mac¬ 
ros assume hardcoded addresses for the host port locations. To modify the 
macros, use the following Write_HSTDATA example as a guideline: 


Write_HSTDATA Macro Reg, Seg 
Local SegReg 
Ifb <Seg> 

SegReg Equ <es> 

Else 

SegReg Equ <Seg> 

Endif 

push bx ; We must save bx (not assumed destroyed) 


mov bx,ds:HstDataAdr ; 
If MEMORY 

Ifidni <Reg>,<bx> ; 

mov ax,Reg ; 

mov SegReg:[bx],ax ; 
Else 

mov SegReg:[bx],Reg ; 
Endif 
Else 

Set_IO [bx] ; 

Ifidni <Reg>,<ax> ; 

out dx,ax ; 

Else 

mov ax,Reg ; 

out dx,ax ; 

Endif 
Endif 

pop bx ; 

Endm 


Load bx with address of HSTDATA 

If reg passed == bx 
then copy to ax 
and send it 

otherwise, send the reg 


Set io address 
If reg passed == ax 
then output ax 

otherwise, move reg to ax 
and output ax 


Restore bx 


You must also search through each of the . asmfiles in the \tiga\cd directo¬ 
ry and replace all occurrences of HSTSEG with the appropriate value in the 
HstSegAdr variable. 
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D.1.20 Rebuilding the Communication Driver 

Rebuilding the TIGA communication driver is a simple operation. First, edit 
the file makecd.bat. This batch is designed to rebuild the communication 
driver for the SBD and must be modified for your board as follows; 

Step 1 : Change lines 3 and 4 to check for an id for your board. Also, 
change the label from SDB to a label for your board. 

Step 2: Change the label on line 7 to your new label. 

Step 3: Modify the description on line 10. 

Step 4: Change line 15 to copy newdef s. inc into def s. inc. 

After making the above modifications, enter makecd yourid from the 
MS-DOS command line from the \tiga\cd directory. Note that your/dis the 
identification added to the makecd.bat batch file in step 1 above.This re¬ 
builds the TIGA communication driver tigacd. exe and copies it into TIGA’s 
main directory \tiga. 
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D.2 Porting the Graphics Manager 


The TIGA Graphics Manager (GM) is the portion of TIGA that resides on the 
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GM are installed in the \tiga\gm directory, with specific portions of the GM 
split into subdirectories under the \tiga\gm directory as follows: 


DiffiC-tfiry_ 

\tiga\gm 

\tiga\gm\corprims 

\tiga\gm\extprims 

\tiga\gm\sdb 


Contents _ 

TIGA graphics manager command executive 
TIGA GM core primitives 
TIGA GM extended primitives 
TIGA GM board-specific functions 


It is suggested that another directory be created underthe\tiga\gm directo¬ 
ry to contain board-specific functions for your particular board. For exam¬ 
ple, assume a directory called \tiga\gm\newgin exists and that all of the 
files from the \tiga\gm\sdb directory have been copied into the 

\tiga\gm\newgm directory. 

The majority of the modifications necessary to port the TIGA GM are made 
to the board-specific functions in the \tiga\gm\newgm directory. 


The following sections describe in detail these modifications. Note that all 
references to filenames are assumed to be files within the \t igaXgmXnewgm 
directory unless otherwise noted. 

The board-specific functions in the \tiga\gm\newgmdirectory are grouped 
into four main categories: 

□ Clearing video memory, 

□ Palette-specific functions, 

□ Configuration functions, and 

□ Miscellaneous functions. 


D.2.1 Video Memory Initialization Functions 

ciearfrm.asm The clear_frame_buffer function uses the fastest possi¬ 
ble method to clear the entire frame buffer to a specified 
color. In the SDB port, shift register transfer cycles are 
used. If this is not possible on the target TMS340 board, 
use a FILL (see the clear_screen function in the file 
ciearscr .asmfor information on how this is done). 

ciearpag. asm The clear_page function uses the fastest possible method 
to clear the entire current drawing page to a specified color. 
Because shift register transfers cannot be used to clear 


D-14 


Porting TIGA 



Porting the Graphics Manager 

only a portion of the entire frame buffer on the SDB, the 
SDB port simply calls the clear_screen function, which 
performs a FILL. The port of this function should use shift 
register transfers if possible. 

clear scr. asm The clear_screen function uses the fastest possible meth¬ 
od to clear the visible portion of the current drawing page to 
a specified color. Although this file is not grouped with the 
other board-specific, video memory initialization functions, 
it may be ported to utilize a faster screen clearing method. 
The SDB port uses the FILL instruction. 

D.2.2 Palette-Specific Functions 

The following functions provide the capability to utilize a color palette on the 
target board. The SDB board uses the TMS34070 color palette, and these 
functions are therefore written to use the TMS34070. They must be modi¬ 
fied if your board has a color palette other than the TMS34070. 

getpaiet. c The function get_palet returns the values in the global pal¬ 

ette array paiet stored in TMS340 memory. Generally, this 
function does not require any porting. 

initpaie. c The function initjpalet sets the palette to EGA default col¬ 
ors. It should replicate these colors through the entire pal¬ 
ette. On the SDB, this is trivial since it has only16 entries. 
Where there are more entries, this will need to be done in a 
loop. If the palette is in ROM and no initialization is possi¬ 
ble, this function should not be implemented and its entry 
should be cleared in the \tiga\gm\primdefs. c file to in¬ 
sure functionjmplemented returns false. 

setpaiet.asm The setjsalet and set_palet_entry functions within 
setpaiet.asm perform initialization of a TMS34070 pal¬ 
ette which stores the palette information in the frame buffer. 
Note that the data stored in the global array paiet (de¬ 
clared in oem.c) is the physical color. The LS 4 bits are 
masked because they are not used in the TMS34070. If the 
palette is in ROM and no initialization is possible, this func¬ 
tion should not be implemented and its entry should be 
cleared in the \tiga\gm\primdefs.c file to ensure 
functionjmplemented returns false. 

Note that the paiet routines use the monitor_fiags field of the 
monitor_ info structure to determine ifthe monitor is coloror monochrome. 
This field selects the use of either the r, g, b values or the i value to initial¬ 
ize the paiet. 
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D.2.3 Configuration Functions 


config.c The get_config function does not require porting. The 
3Gt__corifJ3 function msy rccjuirs pcrtinQ if your board ro- 
quires specific initializations for a particular mode. This ini¬ 
tialization can be performed wherever convenient within 
the set_config function. 


An example of an initialization that may be required for your board Involves 
adding support for OEM mode data specified in the Setup structure. If OEM- 
specific data was added to the oemdata. asm file during the CD port (via the 
OEM_Data structure, see Section D.1.9), then the graphics manager por¬ 
tion of TIGA must be modified to support this data. Normally, the code to 
handle OEM-specific data is added to the set_config function. 


oem. h This file contains constants and type definitions used to ini¬ 

tialize and maintain mode information in the graphics 
manager. The constants VIDEO_MEMORY_START, 
VIDEO_MEMORY_END, and PALET_ENTR!ES should 
be modified to match your board specifications. 
PALET_ENTRIES should contain the number of palette 
entries in your default board mode. The three shared 
memory constants, SHARED_MEM_SIZE, 
SHARED_HOST_ADDR, and SHARED_GSP_ADDR 
should be initialized to values other than 0 If the board sup¬ 
ports shared memory. If it does not, (as in the SDB port), 
initialize to 0. 


The DRAM_RM_RR constant defines the DRAM refresh mode and refresh 
rate. It is ORed with TIGA’s default CONTROL value to initialize the TMS340 
processor CONTROL register. The value of this constant in the SDB port, 
0x08, specifies RAS-only refresh (RR field = 0) and refresh to occur every 
64 local clock periods (RM field = 01). 

The communication buffers, used by TIGA to buffer commands between the 
host and the TMS340, are declared statically in TMS340 memory. The 
oem. h file contains two constants that define the size and number of these 
buffers. 

The NUM_COMM_BUFFERS constant defines the number of communica¬ 
tion buffers. Each communication buffer contains the information for one 
command. Therefore, the more communication buffers defined, the more 
commands that can be queued. The recommended minimum is three com¬ 
munication buffers. 


The COMM_BUFFER_SIZE constant defines the size (in bytes) of the data 
area in each communication buffer. The value assigned to this constant 
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must be at least 1K (1024) bytes and a multiple of 2. This minimum size 
is necessary to ensure that data iess than 1024 bytes long can be sent to 
the TMS340 processor without fear of overflowing the communication buff¬ 
er. 

The MAX_PAGES and MAX_OFFSCREEN constants must be set to the 
maximum number of pages and offscreen areas, respectively, in any oper¬ 
ating mode defined in the communication driver port (see Section D.1.7, 
which defines the PAGEJNFO Structure and Defining the OFF_SCREEN 
structure for more information). This is to insure that there is sufficient 
memory allocated to download these structures to the GM. 

The HEADER and SETUP structures may require modification to support 
any OEM-specific data added to the CD port (via the OEM_Data structure, 
see Section D.1.9 for more information). 

oem. c This file contains the initial configuration and setup structures. 

The data contained in these default structures Is used to ini¬ 
tialize the TIGA environment when the graphics manager is 
initially executed (that is, the GM banner message is dis¬ 
played), and also to statically define an area in TMS340 
memory where mode information from the host is down¬ 
loaded. This configuration is overwritten almost immediately 
thereafter by the current mode information downloaded by the 
host. The data in Default Modeinfo, Default Monitor info. De¬ 
fault Page and Default Offscreen should be initialized with one 
mode from the oemdata. asm file in the communication driver. 

In a future release of TIGA, the copying of the setup structure into a fixed 
length default structure may well be changed to use system heap, thereby 
enabling the setup structure to be dynamic in size. This initial configuration 
is also useful because it enables debug messages to be printed from the 
graphic manager’s main loop during debug of the GM port. 

D.2.4 Miscellaneous Functions 

initvide. c The function init_video_regs initializes the video 

registers for the new mode. This function does not 
require porting unless the target board needs ini¬ 
tialization of some other board-specific latches re¬ 
lating to video timing. 

videnbl.c in the SDB port, the video_enable function does 

nothing. However, for a board that uses a separate 
frame buffer for alternate graphics modes (that is, 
EGA), the video_enable function switches the 
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back-end to display the frame buffer for the correct 
mode. It is called by the host side function set_vi- 
deomode. 


sysf ont. asm Two system fonts are supplied with the TIGA port: 

sYs640.asmand sysi024 .asm. The former is de¬ 
signed for low resolution (640 by 480 and below), 
the latter for high resolution (1024 x 768 and 
above). To select a particular system font, copy it 
into the file sysf ont. asm. This is the files that will 
actually be assembled and linked into the graphics 
manager when it is rebuilt. 

trapvect.asm The functions within the trapvect.asm file per¬ 

form I/O with the TMS340 processor interrupt trap 
vectors. This file requires modifications if the inter¬ 
rupt traps for your board are located in ROM or are 
not contiguous in memory from TMS340 address 
OFFFFFCOO-] 0 (trap 31) to OFFFFFFEO-i 0 (trap 0). 

\tiga\gm\primdefs.c This file defines all implemented core functions 
provided by theTIGA graphics manager. The ad¬ 
dresses of functions that are not implemented in 
your specific board port should be cleared and 
their declarations removed to insure functionjm- 
plemented will return false for these functions. 
Consult the functionjmplemented description 
in Chapter 3 for a list of functions that are likely not 
to be implemented on all boards. 

\tiga\gm\gmdefs.c The Only modification required in the 
\tiga\gm\gmdefs.c file is the pathname of the 
OEM-specific header include file (line 10). Modify 
the pathname of this file to include your OEM-spe¬ 
cific definitions. 

\tiga\gm\tigagm. inc The include file \tiga\gm\tigagm. inc Contains a 
label named OEMMSG as an identifying string for 
your board. Modify the string to the name of the 
board being ported to. This message is displayed 
when the graphics manager is executed. 

There are two possible modes of cursor operation in TIGA. The default 
mode (recommended method) is a display interrupt driven cursor. This en¬ 
tails the cursor being redrawn every frame, which is acceptable for most sys¬ 
tems. In very high resolution displays, however, the overhead of a display 
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interrupt cursor may be unacceptable, in which case a hide/show cursor 
mechanism may be used. To obtain a hide/show cursor, modify the value 
of NON_DI_CURSORfrom Oto 1. The latter cursor flashes quite noticeably, 
whereas the display interrupt cursor is solid. 

D.2.5 Rebuilding the Graphics Manager 

Rebuilding the TIGA graphics manager consists of four parts; 

1) Rebuilding the TIGA core primitives 

2) Rebuilding the TIGA extended primitives 

3) Rebuilding the board-specific functions 

4) Rebuilding the TIGA command executive 

The batch file\tiga\gm\makegm.bat does all of this automatically. Howev¬ 
er, since this batch file and all others associated with rebuilding the GM were 
designed for the SDB port, a few changes are required before rebuilding 
your GM port. 

\tiga\gm\makegm.bat 

This is the main batch file that rebuilds the TIGA 
GM. It is invoked from the DOS command line with 
one argument. 

The following SDB port dependencies may have to 
be modified; 

Q The batch file argument id of SDB 

□ The board-specific directory (\tiga\gm\sdb) 
and make file name (sdbiib.mak) 

□ The board-dependent library filename 

(\tiga\gin\sdb\sdb. lib) 

□ Comments 

After building the GM, makegm.bat automatically attempts to create the new 
GM symbol file \tiga\tiga340.sym by first running tiga.cd and then 
tigaink /cs. It is for this reason that the CD port should be completed prior 
to porting the GM. 

\tiga\gm\tigagm.cmd 

This is the link command file used by gspink. exe to 
build the TIGA graphics manager out file 

tigagm.out. 

The following SDB port dependencies may have to 
be modified; 
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□ The board-dependent library filename 

{\tiga\gm\sdb\sdb.lib) 

□ The values assigned to the labels: 
_start_of_dram 
_bottom_of_stack 
_stack_size 

_end_of_dram 

□ The values assigned to program: 
origin 

length 

□ Comments 


I-1 

Note: 

The label _bottom_of_stack must be double-word (32-bit) aligned, (that is, 
the 5 LSBs must be zero) and must correspond to the address DRAM_End 
in the communication driver. See Section D.1.10. 


\tiga\gm\tigagin.mak. 

This make file rebuilds the GM command executive 
and links all portions of the GM to form the out file 

tigagm.out. 

The following SDB port dependency may have to be 
modified: 

The board-dependent library filename 
\tiga\gin\sdb\sdb.lib located in the list Of 
dependencies for tigagm.out. 

\tiga\gm\newgm\sdblib.mak 

This make file rebuilds the board-dependent library. 

The following SDB port dependencies may have to 
be modified: 

□ The filename of the make file itself 

□ The filename of the board-dependent library 

(sdb.lib) 

After modifying the above files, change your current directory to \tiga\gm 
and enter: makegm yourid, where yourid ls the board identifier you added 
to the makegm.bat batch file. The TIGA graphics manager is then built and 
the output file tigagm.out Copied into the TIGA system directory \tiga. 
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D.3 Verifying Correct Operation 

Included with the TIGA SPK is a comprehensive test suite designed to test 
different aspects of a TIGA port. This test suite can be run from the 
\tigapgms\tests directory by entering tigatest from the DOS command 
line. 

It is suggested that the tests be run in the order displayed on the menu and 
that problems be fixed as they are encountered. 

After verifying correct operation of the test suite, try some of the other test 
programs supplied in the tigapgms directory. 
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D.4 Debugging Your Port 

The TIGA communication driver can be easily debugged using Microsoft’s 
CodeView(R) or comparable debugger. The TiGA graphics manager can 
be debugged by using your board’s TMS340 debugger. The following are 
some suggestions for debugging the TIGA GM: 

The TIGA graphics manager initializes all TMS340 trap vectors upon star¬ 
tup. This can cause havoc with your debugger, which may initialize trap vec¬ 
tors (that is, for single-step capability) before loading and executing the 
TiGA GM. To overcome this problem, modify the init_trap_vectors func¬ 
tion in the file \tiga\gm\sdb\trapvect. asm SO that trap vectors used by 
your debugger are not overwritten. 

After displaying its startup message, the GM then waits for handshaking to 
occur with the host. If necessary, a host TIGA application should be written 
that performs the handshake with the TIGA GM as follows: 

#include <tiga.h> 
main() 

{ 

set_videomode(TIGA,NO_INIT); 
handshake(); 

} 

After performing the handshake, the GM command executive waits for a 
TIGA command from the host. 
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Debugger Support for TIGA 


TIGA is the definitive interface standard for applications software written 
to run on the TMS340 architecture, but it gives no guideiines to deveiopers 
of software with special hardware accessing requirements, such as debug¬ 
gers. 

A set of routines has been included in TIGA to meet the often unique needs 
of debugger developers. This appendix contains the initial TIGA debugger 
routines developed. 


Section Page 

E.1 TIGA Debugger Routines.E-2 

E.2 Compatibility Functions.E-12 
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E.1 TIGA Debugger Routines 

A separate document describing the use of the debugger functions wiii be 
published in the future. The debugger routines development wiii be based 
on the following criteria and on any user feedback received; 

1) Portabie to any TIGA environment, which potentialiy inciudes all 
TMS34010- and TMS34020-based PC graphics displays. 

2) Transparent to share the TMS34010’s host interface registers with an 
application being debugged that uses the host interface for communi¬ 
cation between host and TMS340 resident software. 

3) Able to support the symbolic debug of RLMs (Relocatable Load Mod¬ 
ules), if running in an environment where the TIGA graphics manager 
is active. 

The following is a list of the routines in TIGA that provide debugger support: 

□ get_vector: Get contents of GSP trap vector 

□ set_vector; Set contents of GSP trap vector 

□ set_xstate: Set GSP execution state 

□ get_xstate: Get GSP execution state 

□ get_inemseg: Get high/low bounds of GSP memory segment 

□ set_memseg: Set high/low bounds of GSP memory segment 

□ set_msg: Send a message to the GSP 

□ get_msg: Receive a message from the GSP 

□ save_commstate: Save communication state 

□ rstr_commstate: Restore communication state 

□ oemjnit: Initialize board-specific data 

I-1 

Note: 

The get_vector and set_vector functions are described in Section 3.3 be¬ 
cause their usefulness is not restricted to debuggers. 

I_I 
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Return High/Low Bounds of GSP Memory Segment get_memseg 


Syntax 

Type 

Description 


void get_memseg( addrlo, addhi ); 
unsigned long *addrlo, *addrhi; 

Core 

The get_memseg function is not for general use. It is provided for use by 
debuggers and other such tools that have special hardware accessing re¬ 
quirements. This function returns the low and high bit addresses of a usable 
block of TMS340 memory. Note that if the TIGA graphics manager is active 
(determined by a call to gm_is_alive) then this block of memory has been 
appropriated by the TIGA memory manager, and should not be used. In¬ 
stead, a call to TIGA should be used to allocate usable memory. The two 
arguments, addrio and addrhi, are pointers to unsigned longs where the 
TMS340 addresses are to be placed. 
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get^msg Return a Message from the GSP 
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Syntax unsigned short get_msg(); 

Type Core 

Description The get_msg function is not for general use. It is provided for use by debug¬ 
gers and other such tools that have special hardware accessing require- 
ments.This function receives a 3-bit message from the TMS340. The mes¬ 
sage is located in bits 0 — 2 of the returned value. The fourth bit, bit 3, is 
an interrupt bit and indicates that an interrupt was requested by the host. 
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Return GSP Execution State get_XState 


Syntax 

Type 

Description 


Exampie 


unsigned short get_xstate (); 

Core 

The get_xstate function is not for general use. It is provided for use by de¬ 
buggers and other such tools which have special hardware accessing re¬ 
quirements. This function returns the current TMS340 execution state. The 
returned 16 bits are described below: 


□ 

BitO 

1 if TMS340 is halted, 0 if not. 

□ 

Bit1 

1 if NMI set, 0 if not 

□ 

Bit 2 

1 if NMIMODE set, 0 if not 

□ 

Bits 

1 if cache flushed, 0 if not 

□ 

Bit 4 

1 if cache disabled, 0 if not 

□ 

Bits 5—15 

Reserved for future use 


#include <tiga.h> 
main() 

{ 

if (cd_is_alive()) 

{ 

if (get_xstate() & 1) 

printf("GSP is halted\n"); 
else 

printf("GSP is running\n"); 

} 
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rstr commstate Restore Communication State 


Syntax unsigned short rstr_cominstate () ; 

Type Core 

Description The rstr_commstate function is not for generai use. It is provided for use 
by debuggers and other such tools that have special hardware accessing 
requirements. This function restores the state of TMS340 communications 
to the state it was in after a previous call to save_commstate.The function 
returns zero if unable to save the state, nonzero if it is successful. 
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Save Communication State save_COrnmstate 


Syntax unsigned short save_cominstate () ; 

Type Core 

Description The save_commstate function is not for general use. It is provided for use 
by debuggers and other such tools that have special hardware accessing 
requirements. This function saves the state of TMS340 communications. 
The function returns zero if unable to save the state, nonzero If it is succes¬ 
sful. 
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set_meinseg Set High/Low Bounds of GSP Memory Segment 


Syntax 

Type 

Description 


void set_memseg(addrlo, addhi); 
unsigned long addrlo, addrhi; 

Core 

The set_memseg function is not for general use. It is provided for use by 
debuggers and other such tools that have special hardware accessing re¬ 
quirements. This function sets the low and high bit addresses of a usable 
block of TMS340 memory. It should be called after using some of the 
memory returned by get_memseg to reflect the new memory size. 
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Set a Message from the GSP set_insg 


Syntax 

Type 

Description 


void set_msg( msg ); 
unsigned short msg; 

Core 

The set_msg function is not for general use. It is provided for use by debug¬ 
gers and other such tools that have special hardware accessing require¬ 
ments. This function sends a 3 bit message to the TMS340. The message 
is located in bits 0 — 2 of argument msg. The fourth bit, bit 3, is an interrupt 
bit and requests a host interrupt into the TMS340. 
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set_xstate Set GSP Execution State 
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Syntax void set_xstate(options) ; 

unsigned short options; 

Type Core 

Description The set_xstate function is not for general use. It is provided for use by de¬ 

buggers and other such tools which have special hardware accessing re¬ 
quirements. This function sets the current TMS340 execution state. The re¬ 
turned 16 bits are described below: 

□ Bit 0 1 to halt the TMS340, 0 to let it run 

□ Bit 1 1 to invoke an NMI, 0 to clear NMl 

□ Bit 2 1 to set NMIMODE, 0 to clear NMI 

□ Bit 3 1 to flush cache, 0 to stop cache flush 

□ Bit 4 1 to disable cache, 0 to enable cache 

□ Bits 1 —15 Reserved for future use, must be set to Os 

Exampie #include <tiga.h> 

main () 

{ 

if (cd_is_alive()) 

{ 

set_xstate(1); /* halt the GSP */ 

set_xstate (0); /* run the GSP */ 

} 

} 


E-10 


Debugger Support for TIGA 



Syntax 

Type 

Description 


Initialize Board-Specific Data 06m__init 


void oem_init() 

Core 

This function halts the TMS340 and performs any board-specific initializa¬ 
tion prior to loading a COFF file. 
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E.2 Compatibility Functions 

It is recommended that the compatibility functions not be used by an appli- 
cation programmer. Their functions can be performed by the entry points in 
the previous section and by the communication functions described in 
Chapter 3. These functions talk directly to TMS34010 hardware, which is 
not present on the TMS34020, and their functionality can be emulated only 
on the TMS34020. However, since the TMS34010 has been available for 
some years now, many utilities have been written that interface to the 
TMS34010 hardware directiy. If these utilities are to be ported to TIGA, in 
the understanding that they may not run correctiy on the TMS34020 or other 
future products, then these functions may provide aquick method of porting. 

read_hstaddr Read the TMS34010 host address register 

read_hstadrh Read the TMS34010 host address high register 

read_hstadrl Read the TMS34010 host address low register 

read_hstctl Read the TMS34010 host control register 

read_hstdata Read the TMS34010 host data register 

write_hstaddr Write to the TMS34010 host address register 

write_hstadrh Write to the TMS34010 host address high register 

wrlte_hstadrl Write to the TMS34010 host address low register 

write_hstctl Write to the TMS34010 host controi register 

write_hstdata Write to the TMS34010 host data register 


E-12 


Debugger Support for TIGA 






Read the TMS34010 Host Address Re^ster read_hstaddr 

Syntax unsigned long read_hstaddr(); 

Type Core 

Description This function returns the contents of the host address register of the 
TMS34010. 
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read_hstadrh Read the TMS34010 Host Address High Register 


Syntax 

Type 

Description 


unsigned short read_hstadrh(); 

Core 

This function returns the contents of the host address high register of the 
TMS34010. 
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Read the TMS34010 Host Address Low Register read_hstad rl 


Syntax unsigned short read__hstadrl () ; 

Type Core 

Description This function returns the contents of the host address low register of the 
TMS34010. 
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reacl__hstctl Read the TMS34010 Host Control Register 

Syntax unsigned short read_hstctl(); 

Type Core 

Description This function returns the contents of the host controi register of the 
TMS34010. 


E-16 


Debugger Support for TIG A 



Read the TMS34010 Host Data Register read_hstdata 


Syntax 

Type 

Description 


unsigned short read_hstdata (); 

Core 

This function returns the contents of the host data register of the TMS34010. 
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writ6_hstaddr write to the TMS34010 Host Address Re^ster 

SyntSX void write_hstaddr(value) 

unsigned long value; 

Type Gore 

Description This function writes the 32-bit value supplied into the host address register 
of the TMS34010. 
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Write to the TMS34010 Host Address High Register write_hstadrh 


Syntax 

Type 

Description 


void write_hstadrh(value) 
unsigned short value; 

Core 

This function writes the 16-bit value supplied into the host address high reg¬ 
ister of the TMS34010. 
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writ©_hstadri Write to the TMS34010 Host Address Low Register 

Syntax void write_hstadrl(value) 

unsigned short value; 

Type Core 

Description This function writes the 16-bit vaiue supplied into the host address low reg¬ 
ister of the TMS34010. 
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Write to the TMS34010 Host Control Register write_hstctl 


Syntax 

Type 

Description 


void write_hstctl(value) 
unsigned short value; 

Core 

This function writes the 16-bit vaiue suppiied into the host controi register 
of the TMS34010. Note that in order to function properly, TiGA expects the 
values of the INCR, INCW, and LBL bits in host control to be set in a particu¬ 
lar manner. If these bits are modified, they must be restored prior to invok¬ 
ing another TIGA function or the TIGA environment may be corrupted. 
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write_hstdata write to the TMS34010 Host Data Register 


Syntax 

Type 

Description 


void write_hstdata(value) 
unsigned short value; 

Core 

This function writes the 16-bit value supplied into the host data register of 
theTMS34010. 
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Appendix F 


Glossary 


ADI ™: Autodesk Device Interface, an interface specification used for de¬ 
veloping customized drivers for peripheral devices for Autodesk prod¬ 
ucts. 

A_DIR: An MS-DOS environment variable: identifies the directories 
searched when you specify include and macro files for the TMS340 fami¬ 
ly assembler. 

Al: Application Interface. A part of TIGA consisting of a linkable applica¬ 
tion library and include files that reference TIGA type and function defini¬ 
tions. The Al provides the interface between an application and the TIGA 
communication driver (CD). 

ALM: Absolute Load Module, an extension to the TIGA standard in the 
form of TMS340 object code. It is linked to an absolute memory location 
and stored in a memory image format. An application can load the ALM 
to invoke custom TMS340 functions. 


bitbIt: Bit aligned block transfer. Transfer of a rectangular array of pixel 
information from one location in a bitmap to another with potential of ap¬ 
plying 1 of 16 logical operators during the transfer. 

bitmap: 1. The digital representation of an image in which bits are 
mapped to pixels. 2. A block of memory used to hold raster images in a 
device-specific format. 


CD: Communication Driver. This is a terminate-and-stay-resident pro¬ 
gram that runs on the PC. It is specific to a particular board and is supplied 
by the board manufacturer with the board.The CD contains functions that 
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are invoked by an application’s calls to the Al to communicate via the PC- 
bus to the target TMS340 board. 

G_D!R! An MS-DOS environment variable; it identifies the directories 
searched when you specify include files for the TMS340 C-compiler and 
when specifying object directories for the TMS340 linker. 

COFF: Common Object File Format. An implementation of the object file 
format of the same name developed by AT&T. The TMS340 family com¬ 
piler, assembler, and linker use and produce COFF files. 

command buffer: An area of TMS340 memory used by the TIGA-340 in¬ 
terface buffer data passed by the application and read by the TMS340 
processor. 

command number: An identifier of a function to be invoked by an appli¬ 
cation when the function resides on the TMS340 board. The command 
number consists of three parts: 1) The function type, which specifies the 
format that the parameters are referenced by the TMS340.2) The mod¬ 
ule number, which acts as an identifier to the group of functions. Every 
DLM receives a module number when it is installed. 3) The function num¬ 
ber, which specifies the specific function within the DLM that is to be in¬ 
voked. 

communication buffer: See command buffer. 

configuration: The hardware setting of the TMS340 board, comprising 
display resolution, pixel size, palette size, availability of shared memory, 
etc. 

coprocessor: Microdevice that offloads numeric operations from the 
main processorto speed up overall operation. The TMS34082 is acopro- 
cessor to the TMS34020. The two devices are tightly coupled together. 
The coprocessor adds to the register and instruction capability of the 
TMS34020, resulting in improved handling of floating point arithmetic. In 
this manual, the TMS340 processors are occasionally defined as copro¬ 
cessors to the 80x86 PC processor. This is to emphasize that the 
TMS340 is a programmable processor and can offload much of the bur¬ 
den of the graphics processing and bitmap manipulation from the host 
PC. 

core primitives: A group of TIGA functions that can aiways be invoked 
by an application after TIGA has been installed, as opposed to the ex¬ 
tended primitives, which need to be loaded explicitly by an application. 

C-packet mode: A method of passing parameters in TIGA from the host 
to a function on the TMS340 board. It enables the parameters pushed 
onto the host stack to appear on the TMS340 program stack, as if the 
function had been invoked locally to the TMS340. 
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cursor: In TIGA, this refers to a graphics cursor, which is an icon on the 
screen. The cursor is generaiiy under mouse controi and is used as a 
pointing device in a graphics appiication. 


DDK: Driver Developer’s Kit. A product provided by Texas i nstruments to 
aiiow software deveiopers to write application drivers that interface to the 
TiGA-340 standard, it consists of aTIGA driverforthe Texas Instruments 
software development board (SDB), the TIGA application interface (Al), 
and example programs. 

direct mode: A TIGA mode that is the fastest mechanism to transfer pa¬ 
rameters from the host to a function on the TMS340 board. The parame¬ 
ter data is passed in raw form to a TIGA communication buffer, and the 
TMS340 function receives a pointer to the data. 

DLM: Dynamic Load Module. The DLM is a key part of TIGA’s extensibil¬ 
ity. The module consists of a collection of custom C or assembly routines 
that are not otherwise part of TIGA; thus, they are an extension of TIGA’s 
functionality. The DLM is loaded by an application so that the custom 
TMS340 functions can be invoked by the application. There are two types 
of modules: Relocatable Load Modules (RLMs) and Absolute Load Mod¬ 
ules (ALMs). 


environment or drawing environment: A group of attributes consisting 
of drawing origin, pen size, fill pattern, source and destination bitmaps, 
and line style. 

environment variabie: An MS-DOS variable that can have a string as¬ 
signed by an end-user with the MS-DOS SETcommand. This string can 
be interrogated by a program running under MS-DOS. 

extended primitives: A portion of the TIGA interface functions that can 
be invoked only by a TIGA application after they have been explicitly in- 
stalled.They consist of mostly drawing primitives. 

extensibility: A key feature of TIGA consists of an expandable function 
set. An application programmer can write custom TMS340 functions, 
which can be installed at runtime and invoked from the host application 
in the same manner as the standard TIGA functions. 



font: A set of characters in predefined format that contain alignment infor¬ 
mation, allowing the text routines to produce a visually correct represen¬ 
tation of a given character string. 

frame buffer: A portion of memory used to buffer rasterized data to be 
output to a CRT display monitor. The contents of the frame buffer are of¬ 
ten referred to as the bitmap of the display and contain the logical pixels 
corresponding to the points on the monitor screen. 


GM: Graphics Manager. A TMS340 object file specific to a particular 
board, supplied with the board by the manufacturer. It contains a com¬ 
mand executive to process commands sent from the application, and a 
set of primitives. Some of these are integral TIGA primitives and some 
may be user extensions. 

GSP: Graphics System Processor. A TMS340 family-based system with 
the processing power and control capabilities necessary to manage high- 
performance bitmapped graphics. 


heap: An area of memory that a program can allocate dynamically. 


ISR: interrupt Service Routine. A routine to service an interrupt on the 
TMS340 processor. The most common interrupt is that produced by the 
display interrupt, but other interrupts are available from the host proces¬ 
sor and from two external interrupt pins for window violation. iSRs can 
be downloaded by an application as part of a DIM . 

ISV: Independent Software Vendor. A company that produces software 
products. In this guide it refers to a company that writes a software prod¬ 
uct to interface directly with TIGA. ISVs include Microsoft, Autodesk, etc. 


LIM ™: LIM expanded memory. This system was developed by Lotus, In¬ 
tel, and Microsoft, to define a hardware and software interface for 80x86 
processors running under MS-DOS. LIM provides access to bank- 
switched random access memory. 
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linking loader: A program called TIGALNK that runs under MS-DOS and 
is an integral part of TIGA. It loads and links a dynamic load module with 
user extensions to TIGA into the TIGA Graphics Manager on the 
TMS340. 


memory management: Also referred to as dynamic memory allocation. 
It consists of a group of functions that are used for heap management. 

mode: A particular configuration of a board. An individual board may have 
several modes, for example: 1024-pixels x 768-lines at 8 bits-per-pixel, 
or 640-pixels x 480-lines at 4 bits-per-pixel. 

MS-DOS ™: Microsoft Disk Operating System. A PC-based operating 
system. Because MS-DOS and PC-DOS are esentiaily the same operat¬ 
ing system, this manual uses the term MS-DOS to refer to both systems. 


NMI: Non-Maskable Interruptlhe NMI cannot be disabled; it is usually 
generated by a host processor. 


OEM: Original Equipment Manufacturer. A hardware manufacturing com¬ 
pany. In this user’s guide, it refers to companies that manufacture PC 
graphics add-in boards with a TMS340 processor on them. 

offscreen memory: The part of the frame buffer not being output to a dis¬ 
play. A frame buffer, although typically one contiguous area of linear 
memory, can be viewed as a rectangular area with a specific pitch. Each 
row of the rectangular area corresponds to a row of pixels on the screen. 
If the length is less than the frame buffer pitch, or if there are more lines 
in the frame bufferthan are displayed on the screen, there will be an area 
of the frame buffer not used for display. This area is named offscreen 
memory. Offscreen memory does not include the program memory used 
to store code and data. 

origin: The zero intersection of X and Y axes from which all points are cal¬ 
culated. 



page: Some TMS340 boards may have enough memory in their frame 
bufferto hoid two complete copies of the bitmap output to the screen. This 
technique, sometimes called double buffering, allows one area of the 
screen to be displayed (the display page) while another is being updated 
(the drawing page). When the drawing is completed, the drawing and dis¬ 
play pages are interchanged (page flipping). The flip is synchronized to 
the vertical blank time to ensure a flicker-free display. This technique is 
useful for producing animation sequences. 

palette: A digital-lookup table used in a computer graphics display for 
translating data from the bitmap into the pixel values shown on the dis¬ 
play. 

pattern or fill pattern: SomeTIGA graphics output primitives use a pen 
to fill an area with a pattern rather than a solid color. The pattern is speci¬ 
fied as a 1 -bit-per-pixel map. When the pattern is drawn. Os in the bitmap 
are drawn using the current background color, and 1s are drawn using 
the current foreground color. 

pen or drawing pen: SomeTIGA graphics output primitives use a pen to 
draw an outline. The drawing pen has application-selectable width and 
height. The area covered by the pen can be solid or pattern-filled. 

pixel processing: A logical or arithmetic combination of two pixel values 
(source and destination). 

PixBIt: Pixel Block transfer. Operations on arrays of pixels in which each 
pixel is represented by one or more bits. PixBIt operations are a superset 
of bitbIt operations and include not only commonly used logical opera¬ 
tions, but also integer arithmetic and other multi-bit operations. 

plane: (Also bit plane or color plane). A plane is a bitmap layer in a display 
device with multiple bits per pixel. If the pixel size is n bits and the bits in 
each pixel are numbered Oto n-1, plane 0 is made up of bits 0 from all 
the pixels, and the plane n-1 is made up of bits numbered n-1 from all 
the pixels. A layered graphics display allows planes or groups of planes 
to be manipulated independently of the other planes. 


raster-op: See pixel processing. 

RLM: Relocatable Load Module. An extension to the TIGA standard in the 
form of TMS340 object code. The RLM file is in GOFF file format. It is 
loaded by an application so that the application can invoke custom 
TMS340 functions. 
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SDB: Software Development Board. A PC-compatible board manufac¬ 
tured by Texas Instruments. The SDB contains a TMS34010 graphics 
processor. The two TIGA kits (DDK and SPK) produced by Texas Instru¬ 
ments use the SDB as their target board. 

SDK: Software Developer’s Kit. A Texas Instruments product that allows 
software developers to write TMS340 code. The SDK may be used to de¬ 
velop a TIGA extension, but it is equally applicable for programmers who 
wish to develop stand-alone TMS340 applications. This kit contains the 
DDK and tools such as the C compiler, assembler, and linker. 

shift-register transfer: Atransfer between RAM storage and the internal 
shift register in a video RAM. 

SPK: Software Porting Kit. A Texas Instruments product that allows man¬ 
ufacturers of TMS340-based boards to port TIGA to their board. It con¬ 
tains all TIGA software source code as well as the SDK. 

swizzle: The reversal of every bit in a byte. This is required to convert from 
big-endian processors (where the smallest numbered bit in a word is 
most significant), to little-endian processors (where the smallest num¬ 
bered bit in a word is least significant). 

symbol table: A file containing the symbol names of all the variables and 
functions on the TMS340 side of TIGA. The symbol table is used by the 
linking loader when it is downloading an RLM to resolve references to 
those symbols. This enables the functions in the RLM to call TIGA primi¬ 
tives that are resident on the TMS340 board. 


TIGA ™, TIGA-340 ™: Texas instruments Graphics Architecture. A soft¬ 
ware interface standard that allows a host processor to communicate 
with the TMS340 graphics processors that are typically resident on an 
add-in board. The current implementation of TIGA is for the PC market 
and interfaces the 80x86 processor running under MS-DOS with the 
TMS340. 

TIGACD: This is the file name of the executable program containing the 
communication driver that you run to install TIGA on your system. 

TIGALNK: See linking loader. 

time-out: An application invokes a TIGA TMS340 function by placing a 
command number and appropriate parameters in one of several com- 
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mand buffers. After loading several commands, the command buffers 
may be full; the host has to wait until the TMS340 finishes the current 
command and frees up a buffer. Also, if the function invokegneeds to re¬ 
turn data back to the application, the appiication must wait untii the 
TMS340 completes the command. If the application waits longer than a 
specified time, a time-out warning message is displayed. 

TMS340: A family of graphics system processors and peripherals man¬ 
ufactured by Texas Instruments. 

TMS34010: First-generation graphics processor manufactured by Texas 
Instruments. 

TMS34020: Second-generation graphics processor manufactured by 
Texas Instruments. 

TMS34070: First-generation color palette manufactured by Texas Instru¬ 
ments. 

TMS34082: Floating-point unit manufactured by Texas Instruments; co¬ 
processor to the TMS34020. 

transparency: When a pixel with the attribute of transparency is written 
to the screen, it is effectively invisible, and does not alter that portion of 
the screen it is written to. For example, in a pixel array containing the pat¬ 
tern for the letter A, all pixels surrounding the A pattern could be given 
a special value indicating that they are transparent. When the array is 
written to the screen, the A pattern, but not the pixels in the rectangle con¬ 
taining it, would be invisible. 

trap vector: A specific 32-bit address in TMS340 memory that contains 
the address of an interrupt service routine. 

TSR: Terminate and Stay Resident. A type of program that runs under 
MS-DOS. When it terminates, this type of program leaves a portion of it¬ 
self in memory. 


window: A specified rectangular area of virtual space on the display. 

workspace: An area of memory that is equal in size to a 1-bit-per-pixel 
representation of the current display resolution. Polygon fill functions use 
the workspace as a temporary drawing area before drawing on the 
screen. The workspace can reside either in offscreen memory or in heap. 
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absolute load module, ALM, 3-12, 3-22, 
3-96, 4-2, 4-8, 4-48, 4-49 
installation, 4-8, 4-43 
application interface, Al, 1-4, 2-12, 3-2 
DDK, 2-5 
SPK, 2-5 

attributes, 3-5, 3-6, 3-9, 3-75, 3-76, 3-95, 
3-167, 3-179, 3-180, 4-33, A-7 


B 


background color, 3-5, 3-55, 3-141,3-143, 

3- 145, 4-33 

bitbIt, 3-8, 3-9, 3-14, 3-155, 3-166, 3-184, 

4- 36 


c 


C-packet, 4-10, 4-11,4-13, 4-18, 4-36, 4-41 
cc utility, 2-12 

cdjs_alive, 3-3, 3-16, 3-86 
cl, 2-17 

clear functions, 3-4 
clear_frame_buffer, 3-4, 3-17 
ciear_page, 3-4, 3-18, 3-19 
clear_screen, 3-4, 3-17, 3-18, 3-19 
citiga batch file, 2-12 
COFF loader, 3-86, 4-47 
comm_buff_size, 3-57, A-3 
command buffer, 1-5, 3-3, 3-8, 3-35, 3-40, 

3- 44, 3-57, 3-112, 3-118, 3-129, 3-135, 

4- 12,4-13, 4-16, 4-18, 4-36 


command number, 1-5, 3-103, 4-4, 4-10, 
4-11,4-13,4-36, 4-43 

communication buffer. See command buffer 
communication driver, CD, 1-4, 2-5, 2-6, 

2- 10, 2-11,3-3, 3-8, 3-16, 4-12, 4-13, 
4-16, 4-47 

communication functions, 1-4, 3-11 

compatibility functions, E-12 

CONFIG structure, 3-3, 3-6, 3-8, 3-10, 3-14, 

3- 35, 3-40, 3-44, 3-57, 3-64, 3-66, 3-69, 
3-90, 3-108, 3-112, 3-118, 3-129, 3-135, 

3- 144,4-13,4-16 

See also MODEINFO structure 
cop2gsp, 3-11,3-20 
coprocessor, 3-12, 3-20, 3-57, 3-81 
core primitives, 1-6, 2-5, 2-8, 3-2, 4-10, 4-11, 

4- 32, C-3 
cp_ait, 4-13, 4-14 
cp_cmd, 4-13, 4-14 
cp_ret, 4-13 

cpw, 3-5, 3-21 

create_alm, 3-12, 3-22, 3-159, 4-2, 4-8, 4-9, 
4-32, 4-43, 4-47 

create_esym, 3-12, 3-24, 4-32, 4-47 
current_mode, 3-57, 3-108, A-3 
cursor, 3-10, 3-59, 3-60, 3-90, 3-145, 3-146, 
3-152,3-153,4-33, 4-44, A-5 
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debugger functions, E-2 
deletejont, 3-9, 3-26 
demonstrations and examples, 2-6 
device_rev, 3-57, A-3 
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debugger functions, E-2 
deiete_font, 3-9,3-26 
demonstrations and examples, 2-6 
device_rev, 3-57, A-3 
direct mode, 4-10, 4-11,4-12, 4-18, 4-32, 
4-36,4-41 

disp_hres, 3-58, A-11 
dispjaitch, 3-14, 3-58, A-11 
disp_psize, 3-58, A-11, B-9 
disp_vres, 3-58, A-11 
display_mem_end, 3-57, A-4 
display_mem_start, 3-57, A-3 
dm_cmd, 4-18 
dmjpoly, 4-17, 4-28 
dm_palt, 4-24 
dmjDcmd, 4-25, 4-41 
dm jDget, 4-23 
dmjDoly, 4-17,4-26 
dm_pret, 4-25 
dm_psnd, 4-21 
dm_pstr, 4-24 
dm_ptrx, 4-24 
dm_ret, 4-20 

drawjine, 3-7, 3-27, B-2, B-7 
draw_oval, 3-7, 3-29, B-2, B-7 
draw_ovalarc, 3-7, 3-31, B-2, B-7 
draw_piearc, 3-7, 3-33, B-2, B-7 
draw_point, 3-7, 3-34, B-2, B-7 
draw_polyline, 3-7, 3-8, 3-35, B-2, B-7 
draw_rect, 3-7, 3-37, B-2, B-7 
drawing origin, 3-6, 3-60, 3-61,3-72, 3-142, 
3-145, 3-153, 3-154, A-6, B-5 
driver, 2-10 

driver developer’s kit, DDK, 1 -2, 2-4 
subdirectories, 2-5 
system requirements, 2-2 


E 


ENVIRONMENT structure, 3-5, 3-61,3-145, 
4-33, A-6 


environment variable, 2-11,2-17, 3-22, 3-24, 

3- 49, 3-61,3-96, 3-99, 3-101,4-7, 4-36, 

4- 47 

autoexec modification, 2-9 
extended primitives, 2-5, 2-8, 3-2, 3-3, 3-50, 
3-99, 4-10, 4-11,4-43, B-1, C-5 
DDK, 2-5 

extensibility, 1-3,1-4,1-6, 3-12, 3-22, 3-24, 
3-49, 3-50, 3-63, 3-90, 3-96, 3-99, 3-101, 
3-159,4-1 ' 
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field_extract, 3-11,3-16, 3-38, 4-32 
fieidjnsert, 3-11,3-16, 3-39, 4-32 
fill_convex, 3-7, 3-8, 3-40, B-2, B-6 
filLoval, 3-7, 3-42, B-2, B-6 
fillj3iearc, 3-7, 3-43, B-2, B-6 
filljDolygon, 3-7, 3-8, 3-44, 3-80, 3-174, B-2, 
B-6 

filLrect, 3-7, 3-48, B-2, B-6 
floating point, 2-6,4-40, 4-41 
floating point coprocessor. See coprocessor 
flush_esym, 3-12, 3-49, 4-32 
flush_extended, 3-12, 3-50, 4-32 
font, 2-13, 3-9, 3-26, 3-62, 3-95, 3-97, 3-140, 
3-145, 3-179, 3-180, A-7 
FONTINFO Structure. See font 
foreground color, 3-5, 3-55,3-143,3-145, 
3-158,4-33 

frame_oval, 3-7, 3-51, B-2 
frame_rect, 3-7, 3-52, B-2 
functionjmplemented, 3-3,3-6, 3-20, 3-53, 
3-69, 3-70, B-9 
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get_colors, 3-5, 3-55 

get_config, 3-3, 3-35, 3-57, 3-64, 3-90, 

3- 112, 3-118, 3-129, 3-135, 3-144, 4-13, 

4- 16 

get_curs_state, 3-10, 3-59 
get_curs__xy, 3-10, 3-60 
get_env, 3-5, 3-61,3-175 
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get_fontinfo, 3-9, 3-62 
getJsr_priorities, 3-12, 3-63,3-96,3-101, 

3-159, 4-32, 4-44, 4-45 
get_modeinfo, 3-3, 3-57, 3-64, 3-144,4-32, 

A-11 

get_nearest_color, 3-6, 3-65, B-9 
get_offscreen_memoty, 3-11,3-58, 3-66, 

3-174,A-12, A-14 
getjjalet, 3-6,3-69, B-9 
get_palet_entry, 3-6, 3-69, 3-70 
get_pixel, 3-10, 3-72 
get_pmask, 3-5, 3-73, 3-164 
getjDpop, 3-5, 3-74, 3-164 
get_textattr, 3-9, 3-75 
get_transp, 3-5, 3-76 
get_vector, 3-11,3-77 
get_videomode, 3-3, 3-78, 3-171,4-32 
get_windowing, 3-5, 3-79 
get_wksp, 3-8, 3-44, 3-80 
graphics manager, GM, 1-5, 2-5, 2-10, 3-3, 

3- 8, 3-16, 3-24, 3-86, 3-96, 3-101,4-14, 

4- 32, 4-35, 4-44, 4-47, 4-49 
graphics output functions, 3-7, B-2 
graphics utility functions, 3-10 
gsp_calloc, 3-11,3-85 
gsp_execute, 3-3, 3-16, 3-86, 3-106 
gsp_free, 3-11,3-87 

gsp_malloc, 3-11,3-66, 3-88, 3-162, 3-174 
gsp_maxheap, 3-11,3-89 
gsp_minit, 3-11,3-57, 3-90 
gsp_realloc, 3-11,3-91 
gsp2cop, 3-11,3-53, 3-81 
gsp2gsp, 3-11,3-82 
gsp2host, 3-11,3-16, 3-83, 4-32 
gsp2hostxy, 3-11,3-16, 3-84, 4-32 


H 


host2gsp, 3-11,3-16, 3-92, 4-32 
host2gspxy, 3-11,3-16, 3-93, 4-32 



include files, 2-5, 2-8, 2-9, 2-18, 4-11,4-14, 
4-32, 4-43, A-1 

init_palet, 3-6, 3-53, 3-94, B-10 
init_text, 3-9, 3-95 

Initialization, 2-10, 3-3, 3-90, 3-94, 3-95, 

3- 145, 4-46, 4-49 

instalLalm, 3-12, 3-63, 3-96, 3-159, 4-3, 4-9, 

4- 11,4-32,4-43,4-47 
instalLfont, 3-9, 3-95, 3-97 

installjDrImitives, 3-3, 3-12, 3-99, 4-10, 4-32 
instalLrIm, 3-12, 3-24, 3-63, 3-101,3-159, 
4-3, 4-7, 4-11,4-32, 4-38, 4-45, 4-47 
InstalLusererror, 3-3, 3-4, 3-35, 3-41,3-45, 
3-103, 3-113, 3-119, 3-129, 3-135, 3-168, 
3-171,4-32 

installation, 2-4, 4-7, 4-38, 4-44 
interrupt, 2-6, 2-11,3-12, 3-63, 3-79, 3-96, 

3- 101,3-159, 3-173, 4-2, 4-4, 4-5, 4-32, 

4- 33, 4-35, 4-44, 4-45, 4-46 



lib, 2-17 
link, 2-17 

linking loader, 1-5, 2-10, 3-22, 3-24, 3-49, 
4-1,4-2, 4-9, 4-47 
Imo, 3-10, 3-105 
loadcoff, 3-3, 3-16, 3-86, 3-106 
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make, 2-6, 2-12, 2-17,4-38 
math/graphics, 1-2, 2-12, 2-13 
memory management, 3-2, 3-11,4-2, A-3 
mg2tiga utility, 2-13 
MODEINFO structure, 3-3, 3-57, 3-64, 
3-144, A-11 

MONITORINFO structure, A-13 


Index-3 




Index 


H 


num_modes, 3-57, A-3 
nu!Ti_offscrn_ar 08 .s, 3-58, 3-66, A-12 
numjDages, 3-58, 3-108, A-12 


o 


offscreen, 3-4, 3-18, 3-19, 4-33, A-12, A-14 



page, 3-4, 3-10, 3-18, 3-58, 3-107, 3-108, 
3-144, 4-33, A-12 
PAGE structure, A-15 
page_busy, 3-10, 3-107 
page_flip, 3-10, 3-108, A-15 
PALET structure, A-16 
palet_gun_depth, 3-6, 3-58, A-11, B-9 
paletjnset, 3-58, A-12 
palet__size, 3-58, 3-69, A-12 
palette, 3-6, 3-18, 3-65, 3-69, 3-70, 3-94, 
3-160, 3-161, A-11, A-16, B-9 
patnfilLconvex, 3-7, 3-8, 3-112, B-2, B-4, B-6 
patnfill_oval, 3-7, 3-114, B-2, B-4, B-6 
patnfilljDiearc, 3-7, 3-115, B-2, B-4, B-6 
patnfilljDolygon, 3-7, 3-8, 3-118, B-2, B-4, 

B-6 

patnfili__rect, 3-7, 3-120, B-2, B-4, B-6 
patnframe_oval, 3-7, 3-121, B-2, B-4 
patnfranne_rect, 3-7, 3-122, B-2, B-4 
patnpenjine, 3-7, 3-123, B-2, B-4, B-8 
patnpen_ovalarc, 3-7, 3-126, B-2, B-4, B-8 
patnpen_piearc, 3-7, 3-127, B-2, B-4, B-8 
patnpen_point, 3-128, B-2, B-4, B-8 
patnpen_polyrme, 3-7, 3-8, 3-129, B-2, B-4, 
B-8 

pattern, 3-5, 3-6, 3-7, 3-61,3-112, 3-114, 
3-115, 3-118, 3-120, 3-121,3-122, 3-123, 
3-126, 3-127, 3-128, 3-129, 3-139, 3-145, 
3-162, 4-33, A-6, A-17, B-2, B-4 
PATTERN structure. See pattern 
peek_breg, 3-10, 3-130 


pen, 3-6, 3-7, 3-61,3-123, 3-126, 3-127, 

3-128, 3-129, 3-131,3-132, 3-133, 3-134, 
3-135, 3-145, 3-163, A-6, B-2, B-8 
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pen_ovalarc, 3-7, 3-132, B-2, B-8 
pen_piearc, 3-7, 3-133, B-2, B-8 
pen_point, 3-7, 3-134, B-2, B-8 
pen_polyline, 3-7, 3-8, 3-135, B-2, B-8 
pixel array function, 3-8 
pixel mask, 3-58, A-11 
pixel processing, 3-5, 3-74, 3-76, 3-145, 
3-146, 3-165, A-5 

plane mask, 3-5, 3-73, 3-145, 3-164 
poke_breg, 3-10, 3-136 
poly drawing functions, 3-8, 4-16, B-2, B-6, 
B-8 

porting TIGA, D-1 
program_mem_end, 3-57, A-3 
program_mem_start, 3-57, A-3 
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register usage, 4-33 

relocatable load module, RLM, 3-22, 3-101, 
4-2, 4-5, 4-38, 4-48, 4-49 
Installation, 4-7 
rmo, 3-10,3-137 
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screen__high, 3-58, A-11 

screen_wide, 3-58, A-11 

seedjill, 3-7, 3-66, 3-138 

seed_patnfill, 3-7, 3-139 

selectjont, 3-9, 3-140 

set_bcolor, 3-5, 3-141 

set_clip_rect, 3-5, 3-14, 3-142 

set_colors, 3-5, 3-143 

set_config, 3-3, 3-144, 4-32, A-3 

set_curs_shape, 3-10, 3-90, 3-146, A-5 

set_curs__state, 3-10, 3-152 

set_curs__xy, 3-10, 3-146, 3-153, A-5 

set_draw_origin, 3-5, 3-61,3-154, A-6, B-5 

set_dstbm, 3-8, 3-14, 3-61,3-155, A-6 

set_fcolor, 3-5, 3-158, A-7 
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setjnterrupt, 3-12, 3-159, 4-44, 4-45 
set_palet, 3-6, 3-53, 3-69, 3-160, B-9 
set_palet_entry, 3-6, 3-53, 3-69, 3-161, B-9 
set_patn, 3-5, 3-162, A-17 
See also pattern 

set_pensi 2 e, 3-5, 3-123, 3-163, A-6 
See also pen 

set_pmask, 3-5, 3-73, 3-164 
set_ppop, 3-5, 3-74, 3-165 
set_srcbm, 3-8, 3-14, 3-61,3-166, 3-184, 

A-6 

set_textattr, 3-9, 3-167, 3-179, A-10 
set_timeout, 3-3, 3-4, 3-168, 4-32 
setjransp, 3-5, 3-53, 3-169, 3-181,3-182 
set_vector, 3-11,3-170 
set_videomode, 2-10, 3-3, 3-16, 3-78, 3-145, 
3-171,4-32,4-38, 4-43 
set_windowing, 3-5, 3-79, 3-173 
set_wksp, 3-8, 3-44, 3-66, 3-80, 3-90, 3-118, 

3- 174 

share_gsp_addr, 3-57, A-4 
share_host_addr, 3-57, A-4 
share_mem_size, 3-57, A-4 
software developer’s kit, SDK, 1-2 
software porting kit, SPK, 1-2, 2-4 
subdirectories, 2-5 
system requirements, 2-2 
stack_size, 3-57, 3-90, A-4 
styledjine, 3-7, 3-61,3-175, A-6 
swap_bm, 3-8, 3-177 
symbol table, 3-12, 3-24, 3-49, 3-50, 4-2, 

4- 48, 4-49 

synchronize, 3-3, 3-4, 3-178, 4-32, 4-40 
syntax and programming examples, 2-18 
sysjlags, 3-20, 3-57, 3-81, A-3 
system requirements, 2-2 



text, 2-13, 3-9, 3-26, 3-62, 3-75, 3-95, 3-97, 

3- 140, 3-167, 3-179, 3-180, 4-33, A-7 
text_out, 3-9,3-167, 3-179 
text_width, 3-9, 3-167, 3-180 
TIGAEXT section, 3-96, 3-101,4-4, 4-5, 

4- 11,4-13, 4-38, 4-39, 4-45, 4-47 
TIGAISR section, 4-4, 4-5, 4-44, 4-45, 4-47 
TIGALNK, 1-5, 2-10, 3-22, 3-24, 3-49, 4-1, 

4-2, 4-9, 4-47 

TIGAMODE utility, 2-6, 2-16, 3-3 
transp_off, 3-5, 3-181 
transp_on, 3-5, 3-182 

transparency, 3-5, 3-53, 3-76, 3-145, 3-169, 
3-181,3-182,4-33 
trap vector, 3-11,3-77, 3-170 
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utilities, 2-5, 2-12, 2-17, 3-3, 3-10 
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version_number, 3-57, A-3 
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wait_scan, 3-10, 3-183 
windowing, 3-6, 3-79, 3-142, 3-145, 3-173 
wksp_addr, 3-58, 3-80, 3-174, A-12 
wksp_pitch, 3-58, 3-80, 3-174, A-12 
workspace, 3-8, 3-44, 3-58, 3-66, 3-80, 
3-118, 3-174 
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zoom_rect, 3-8, 3-66, 3-184 
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TI Distributors 


ALABAMA: Huntsville (205) 837-7530. 

ARIZONA: Phoenix (602) 995-1007; 

Tucson (602) 292-2640. 

CALIFORNIA: Irvine (714) 660-1200; 

Roseville (916) 786-9208; 

San Diego (619) 278-9601; 

Santa Clara (408) 980-9000; 

Torrance (213)217-7010; 

Woodland Hills (818) 704-7759. 

COLORADO: Aurora (303) 368-8000. 
CONNECTICUT: Wallingford (203) 269-0074. 

FLORIDA: Altamonte Springs (305) 260-2116; 
Ft. Lauderdale (305) 973-8502; 

Tampa (813) 885-7411. 

GEORGIA: Norcross (404) 662-7900. 
ILLINOIS: Arlington Heights (312) 640-2925. 

INDIANA: Carmel (317) 573-6400; 

Ft. Wayne (219) 424-5174. 

IOWA: Cedar Rapids (319) 395-9550. 
KANSAS: Overland Park (913) 451-4511. 
MARYLAND: Columbia (301) 964-2003. 
MASSACHUSETTS: Waltham (617) 895-9100. 

MICHIGAN: Farmington Hills (313) 553-1569; 
Grand Rapids (616) 957-4200. 

MINNESOTA: Eden Prairie (612) 828-9300. 
MISSOURI: St. Louis (314) 569-7600. 

NEW JERSEY: Iselln (201) 750-1050. 

NEW MEXICO: Albuquerque (505) 345-2555. 


NEW YORK: East Syracuse (315) 463-9291; 
Melville (516) 454-6600; 

PIttsford (716) 385-6770; 

Poughkeepsie (914) 473-2900. 


NORTH CAROLINA: Charlotte (704) 527-0933; 
Raleigh (919) 876-2725. 


OHIO: Beachwood (216) 464-6100; 
Beaver Creek (513) 427-6200. 


OREGON: Beaverton (503) 643-6758. 
PENNSYLVANIA: Blue Bell (215) 825-9500. 
PUERTO RICO: Hato Rey (809) 753-8700. 
TENNESSEE: Johnson City (615) 461-2192. 

TEXAS: Austin (512) 250-7655; 

Houston (713) 778-6592; 

Richardson (214) 680-5082; 

San Antonio (512) 496-1779. 


UTAH: Murray (801) 266-8972. 
WASHINGTON: Redmond (206) 881-3080. 
WISCONSIN: Brookfield (414) 782-2899. 


CANADA: Nepean, Ontario (613) 726-1970; 
Richmond Hill, Ontario (416) 884-9181; 

St. Laurent, Quebec (514) 336-1860. 


TI Regional 
Technology Centers 

CALIFORNIA: Irvine (714) 660-8105; 

Santa Clara (408) 748-2220; 

GEORGIA: Norcross (404) 662-7945. 

ILLINOIS Arlington Heights (312) 640-2909. 
MASSACHUSETTS: Waltham (617) 895-9196. 

TEXAS: Richardson (214) 680-5066. 

CANADA: Nepean, Ontario (613) 726-1970. 


TI AUTHORIZED DISTRIBUTORS 
Arrow/Kierulff Electronics Group 
Arrow (Canada) 

Future Electronics (Canada) 

GRS Electronics Co., Inc. 
Hall-Mark Electronics 
Marshall industries 
Newark Electronics 
Schweber Electronics 
Time Electronics 
Wyle Laboratories 
Zeus Components 

-OBSOLETE PRODUCT ONLY- 
Rochester Electronics, Inc. 
Newburyport, Massachusetts 
(508) 462-9332 


ALABAMA: Arrow/Kierulff (205) 837-6955; 

Hall-Mark (205) 837-8700; Marshall (205) 881-9235; 
Schweber (205) 895-0480. 

ARIZONA: Arrow/Kierulff (602) 437-0750; 

Hall-Mark (602) 437-1200; Marshall (602) 496-0290; 
Schweber (602) 431-0030; Wyle (602) 866-2888. 

CALIFORNIA: Los Angeles/Orange County: 
Arrow/Kierulff (818) 701-7500, (714) 838-5422; 
Hall-Mark (818) 773-4500, (714) 669-4100; 

Marshall (818) 407-0101, (818) 459-5500, 

(714) 458-5395; Schweber (818) 880-9686; 

(714) 863-0200, (213) 320-8090; Wyle (818) 880-9000, 
(714) 863-9953; Zeus (714) 921-9000; (818) 889-3838; 
Sacramento: Hall-Mark (916) 624-9781; 

Marshall (916) 635-9700; Schweber (916) 364-0222; 
Wyle (916) 638-5282; 

San Diego: Arrow/Kierulff (619) 565-4800; 

Hall-Mark (619) 268-1201; Marshall (619) 578-9600; 
Schweber (619) 450-0454; Wyle (619) 565-9171; 

San Francisco Bay Area: Arrow/Kierulff (408) 745-6600, 
Hall-Mark (408) 432-0900; Marshall (408) 942-4600; 
Schweber (408) 432-7171; Wyle (408) 727-2500; 

Zeus (408) 998-5121. 

COLORADO: Arrow/Kierulff (303) 790-4444; 

Hall-Mark (303) 790-1662; Marshall (303) 451-8383; 
Schweber (303) 799-0258; Wyle (303) 457-9953. 

CONNETICUT: Arrow/Kierulff (203) 265-7741; 
Hall-Mark (203) 271-2844; Marshall (203) 265-3822; 
Schweber (203) 264-4700. 

FLORIDA: Ft. Uuderdale: 

Arrow/Kierulff (305) 429-8200; Hall-Mark (305) 971-9280; 
Marshall (305) 977-4880; Schweber (305) 977-7511; 
Orlando; Arrow/Kierulff (407) 323-0252; 

Hall-Mark (407) 830-5855; Marshall (407) 767-8585; 
Schweber (407) 331-7555; Zeus (407) 365-3000; 
Tampa: Hall-Mark (813) 530-4543; 

Marshall (813) 576-1399; Schweber (813) 541-5100. 

GEORGIA: Arrow/Kierulff (404) 449-8252; 

Halt-Mark (404) 447-8000; Marshall (404) 923-5750; 
Schweber (404) 449-9170. 

ILLINOIS: Arrow/Kierulff (312) 250-0500; 

Hall-Mark (312) 860-3800; Marshall (312) 490-0155; 
Newark (312) 784-5100; Schweber (312) 364-3750. 

INDIANA: Indianapolis; Arrow/Kierulff (317) 243-9353; 
Hall-Mark (317) 872-8875; Marshall (317) 297-0483; 
Schweber (317) 343-1050. 

IOWA: Arrow/Kierulff (319) 395-7230; 

Schweber (319) 373-1417. 

KANSAS: Kansas City: Arrow/Kierulff (913)541-9542; 
Hall-Mark (913) 888-4747; Marshall (913) 492-3121; 
Schweber (913) 492-2922. 


MARYLAND: Arrow/Kierulff (301) 995-6002; 

Hall-Mark (301) 988-9800; Marshall (301) 235-9464; 
Schweber (301) 840-5900; Zeus (301) 997-1118. 

MASSACHUSETTS Arrow/Kierulff (508) 658-0900; 
Hall-Mark (508) 667-0902; Marshall (508) 658-0810; 
Schweber (617) 275-5100; Time (617) 532-6200; 

Wyle (617) 273-7300; Zeus (617) 863-8800. 

MICHIGAN: Detroit: Arrow/Kierulff (313) 462-2290; 
Hall-Mark (313) 462-1205; Marshall (313) 525-5850; 
Newark (313) 967-0600; Schweber (313) 525-8100; 
Grand Rapids: Arrow/Kierulff (616) 243-0912. 

MINNESOTA: Arrow/Kicrulff (612) 830-1800; 

Hall-Mark (612) 941-2600; Marshall (612) 559-2211; 
Schweber (612) 941-5280. 

MISSOURI: St. Louls: Arrow/Kierulff (314) 567-6888; 
Hall-Mark (314) 291-5350; Marshall (314) 291-4650; 
Schweber (314) 739-0526. 

NEW HAMPSHIRE: Arrow/Kierulff (603) 668-6968; 
Schweber (603) 625-2250. 

NEW JERSEY: Arrow/Kierulff (201) 538-0900, 

(609) 596-8000; GRS Electronics (609) 964-8560; 
Hall-Mark (201) 575-4415, (201) 882-9773, 

(609) 235-1900; Marshall (201) 882-0320, 

(609) 234-9100; Schweber (201) 227-7880. 

NEW MEXICO: Arrow/Kierulff (505) 243-4566. 

NEW YORK: Long Island: 

Arrow/Kierulff (516) 231-1009; Hall-Mark (516) 737-0600; 
Marshall (516) 273-2424; Schweber (516) 334-7474; 
Zeus (914) 937-7400; 

Rochester: Arrow/Kierulff (716) 427-0300; 

Hall-Mark (716) 425-3300; Marshall (716) 235-7620; 
Schweber (716) 424-2222; 

Syracuse: Marshall (607) 798-1611. 

NORTH CAROLINA: Arrow/Kierulff (919) 876-3132, 
(919) 725-8711; Hall-Mark (919) 872-0712; 

Marshall (919) 878-9882; Schweber (919) 876-0000. 

OHIO: Cleveland: Arrow/Kierulff (216) 248-3990; 
Hall-Mark (216) 349-4632; Marshall (216) 248-1788; 
Schweber (216) 464-2970; 

Columbus: Hall-Mark (614) 888-3313; 

Dayton: Arrow/Kierulff (513) 435-5563; 

Marshall (513) 898-4480; Schweber (513) 439-1800. 

OKLAHOMA: Arrow/Kierulff (918) 252-7537; 
Schweber (918) 622-8003. 

OREGON: Arrow/Kierulff (503) 645-6456; 

Marshall (503) 644-5050; Wyle (503) 640-6000. 

PENNSYLVANIA: Arrow/Kierulff (412) 856-7000, 

(215) 928-1800; GRS Electronics (215) 922-7037; 
Marshall (412) 963-0441; Schweber (215) 441-0600, 
(412) 963-6804. 

TEXAS: Austin: Arrow/Kieruiff (512) 835-4180; 
Hall-Mark (512) 258-8848; Marshall (512) 837-1991; 
Schweber (512) 339-0088; Wyle (512) 834-9957; 
Dallas: Arrow/Kierulff (214) 380-6464; 

Hall-Mark (214) 553-4300; Marshall (214) 233-5200; 
Schweber (214) 661-5010; Wyle (214) 235-9953; 

Zeus (214) 783-7010; 

El Paso: Marshall (915) 593-0706; 

Houston: Arrow/Kierulff (713) 530-4700; 

Hall-Mark (713) 781-6100; Marshall (713) 895-9200; 
Schweber (713) 784-3600; Wyle (713) 879-9953. 

UTAH: Arrow/Kierulff (801) 973-6913; 

Hall-Mark (801) 972-1008; Marshall (801) 485-1551; 
Wyle (801) 974-9953. 

WASHINGTON: Arrow/Kierulff (206) 575-4420; 
Marshall (206) 486-5747; Wyle (206) 881-1150. 

WISCONSIN: Arrow/Kierulff (414)792-0150; 

Hall-Mark (414) 797-7844; Marshall (414) 797-8400; 
Schweber (414) 784-9020. 

CANADA: Calgary: Future (403) 235-5325; 
Edmonton: Future (403) 438-2858; 

Montreal: Arrow Canada (514) 735-5511; 

Future (514)694-7710; 

Ottawa: Arrow Canada (613) 226-6903; 

Future (613) 820-8313; 

Quebec City: Arrow Canada (418) 871-7500; 

Toronto: Arrow Canada (416) 672-7769; 

Future (416) 638-4771; Marshall (416) 674-2161; 
Vancouver: Arrow Canada (604) 291-2986; 

Future (604) 294-1166. 


Customer 
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Response Center 

TOLL FREE: (800) 232-3200 

OUTSIDE USA: (214)995-6611 

(8:00 a.m. - 5:00 p.m. CST) 
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TI Worldwide 
Sales Offices 


ALABAMA: Huntsvilto: 500 Wynn Drive. Suite 614. 
Huntsville, AL 35805, <205) 837-7530. 

ARIZONA: Phoenix: 8825 N. 23rd Ave.. Phoenix. 

AZ 85021,1602) 995-1007:TUCS0N: 818 W. Miracle 
Mile. Suite 43, Tucson, AZ 85705. (602) 292-2640. 

CAUPORNIA: Irvine: 17891 Cartwright Or., Irvine, CA 
92714, (714) 660-1200; Roseville: 1 Sierra Gate 
Plaza, Roseville, CA 95678, (916) 786-9208: 

San Oisgo: 4333 View Ridge Ave., Suite 100, 

San Diego. CA 92123, (619) 278-9601; 

Bants Clara: 5353 Betsy Ross Or., Santa Clara, CA 
95054, (408) 980-9000, Torrance: 690 Knox St.. 
Torrance. CA 90502, (213) 217-7010, 

Woodland HMs: 21220 Erwin St.. Woodland Hills, 

CA 91367. (818) 704-7759. 

COLORADO: Aurora: 14(X) S. Potomac Ave., 

Suite 101, Aurora, CO 80012, (303) 368-8000. 

CONNECTICUT: Wallingford: 9 Barnes Industrial Park 
Rd., Barnes Industrial Park, Wallingford. 

CT 06492, (203) 269-0074. 

FLORIDA: Altamonte Springe: 370 S. North Lake Blvd. 
Altamonte Springs, FL 32701. 1305) 260-2116; 

Ft. Uuderdala: 2950 N.W. 62nd St., 

Ft. Lauderdale. FL 33309, (305) 973-8502; 

Tampa: 4803 George Rd., Suite 390, 

Tampa, FL 33634, (813) 885-7411. 

GEORGIA: Norcross: 5515 Spalding Drive, Norcross. 
GA 30092, (404) 662-7900 

ILLINOIS: ArNngtan Heights: 515 W. Algonquin, 
Arlington Heights. IL 60005, (312) 640-2925. 

INDIANA: Ft. Wayne: 2020 Inwoed Dr.. 

Ft. Wayne, IN 46815, (219) 424-5174; 

Carmel: 550 Congressional Dr., Carmel. IN 46032. 
(317) 573-6400. 

IOWA: Cedar Rapids: 373 Collins Rd. NE, Suite 201. 
Cedar Rapids. lA 52402, (319) 395-9550. 

KANSAS; Overland Park; 7300 College Blvd., Lighten 
Plaza, Overland Park, KS 66210, (913) 451-4511. 

MARYLAND: Columbia: 8815 Centre Park Dr.. 
Columbia MD 21045, (301) 964-2003. 

MASSACHUSETTS: Wahham: 950 Winter St.. 
Waltham, MA 02154, (617) 895-9100. 

MICHIGAN: Farmington HMs: 33737 W. 12 Mile Rd.. 
Farmington Hills, Ml 48018, (313) 553-1569. 

Grand Rapids: 3075 Orchard Vista Dr. S.E.. 

Grand Rapids, Ml 49506. (616) 957-4200. 

MINNESOTA: Eden Prairie: 11000 W. 78th St.. 

Eden Prairie, MN 55344 (612) 828-9300. 

MISSOURI: St. Louis: 11816 Borman Drive. 

St. Louis, MO 63146, (314) 569-7600. 

NEW JERSEY: IseNn: 485E U.S. Route 1 South, 
Parkway Towers, Iselin, NJ 08830 (201) 750-1050. 

NEW MEXICO: Albuqiiorqua: 2820-0 Broadbent Pkwy 
NE. Albuquerque, NM 87107, (505) 345-2555. 

NEW YORK: East Syracuse: 6365 Collamer Or.. 

East Syracuse, NY 13057, (315) 463-9291; 

MalvWe: 1895 Walt Whitman Rd., P.O. Box 2936, 
Melville, NY 11747, (516) 454-6600; 

PMsford; 2851 Clover St., Pittsford, NY 14534, 

(716) 385-6770; 

Poughkeepsie: 385 South Rd., Poughkeepsie. 

NY 12601. (914) 473-2900. 

NORTH CAROUNA: Charlotte: 8 Woodlawn Green, 
Woodlawn Rd., Charlotte, NC 28210, (704) 

527-0933; Raleigh: 2809 Highwoods Blvd.. Suite 100. 
Raleigh, NC 27625, (919) 876-2725. 

OHIO: Beachwood: 23775 Commerce Park Rd.. 
Beachwood, OH 44122, (216) 464-6100; 

Beavercreek: 4200 Colonel Glenn Hwy.. 

Beavercreek. OH 45431, (513) 427-6200. 


OREGON: Beaverton: 6700 SW 105th St.. Suite 110, 
Beaverton, OR 97005, (503) 643-6758. 
PENNSYLVANIA: Blua BeN: 670 Sentry Pkwy. 

Diyj Qjij^ OA 10422. (215) 825-9500 

PUERTO RICO: Hato Rey: Mercantil Plaza Bldg., 

Suite 505, Hato Rey, PR 00918, (809) 753-8700. 

TENNESSEE: Johnson City: Erwin Hwy, 

P.O. Drawer 1255. Johnson City. TN 37605 
(615)461-2192. 

TEXAS: Austin: 12501 Research Blvd., Austin, TX 
78759, (512) 250-7655; Richardson: 1001 E. 
Campbell Rd., Richardson, TX 7S081. 

(214) 680-5082; Houston: 9100 Southwest Frwy., 
Suite 250, Houston, TX 77074, (713) 778-6592; 

San Antonio: 1000 Central Parkway South, 

San Antonio, TX 78232. (512) 496-1779. 

UTAH: Murray: 5201 South Green St.. Suite 200. 
Murray, UT 84123, (801) 266-8972. 

WASHINGTON: Redmond: 5010 148th NE. Bldg B, 
Suite 107, Redmond, WA 98052. (206) 881-3080. 

WISCONSIN: Brookfield: 450 N. Sunny Slope, Suite 
150, Brookfield, Wl 53005, (414) 782-2899. 

CANADA: Nepean: 301 Moodie Drive, Mallorn Center, 
Nepean, Ontario, Canada, K2H9C4, 

(613) 726-1970. Richmond HW: 280 Centre St. E.. 
Richmond Hill L4C1B1. Ontario, Canada 
(416) 884-9181; St. Laurent: Ville St. Laurent 
Quebec, 9460 Trans Canada Hwy., St. Laurent, 
Quebec, Canada H4S1R7, (514) 336-1860. 


ARGENTINA: Texas Instruments Argentina Viamonte 
1119, 1053 Capital Federal, Buenos Aires, Argentina, 
541/748-3699 

AUSTRALIA (& NEW ZEALAND); Texas Instruments 
Australia Ltd.: 6-10 Talavera Rd., North Ryde 
(Sydney), New South Wales, Australia 2113, 

2 -r 887-1122; 5th Floor. 418 St. KildVRoad. 
Melbourne, Victoria, Australia 3004, 3 -f 267-4677; 
171 Philip Highway, Elizabeth, South AustrMia 5112, 
8 255-2066. 

AUSTRIA: Texas Instruments Ges.m.b.H.: 
Industriestrabe B/16, A-234S Brunn/Gebirge. 
2236-846210. 

BELGIUM: Texas Instruments N.V. Belgium S.A.: 11. 
Avenue Jules Bondetlaan 11, 1140 Brussels, Belgium, 
(02) 242-3080. 

BRAZIL: Texas Instruments Electronicos do Brasil 
Ltda.; Rua Paes Leme, 524-7 Andar Pinheiros, 05424 
Sao Paulo, Brazil, 0815-6166. 

DENMARK: Texas Instruments A/S, Mairelundvej 46E. 
2730 Herlev, Denmark, 2 - 91 74 00. 

FINLAND: Texas Instruments Finland OY: 

Ahertajantie 3, P.O. Box 81. ESPOO. Finland, (90) 
0-461-422. 

FRANCE: Texas Instruments France: Paris Office, BP 
67 8-10 Avenue Morane-Saulnier, 78141 Velizy- 
Villacoublay cedex (1) 30 70 1003. 

GERMANY (Fed. Republic of Germany): Texas 
Instruments Deutschland GmbH: Haggertystrasse 1, 
8050 Freising, 8161 -f 80-4591; Kurfuerstendamm 
195/196, 1000 Berlin IS, 30-r882-7365; III. Hagen 
43/Kibbelstrasse, .19, 4300 Essen. 201-24250; 
Kirchhorsterstrasse 2, 3000 Hannover 51, 
511-^648021; Maybachstrabe 11. 7302 Ostfildern 
2-Nelingen, 711-r 34030. 
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HONG KONG: Texas Instruments Hong Kong Ltd.. 8th 
Floor, World Shipping Ctr., 7 Canton Rd.. Kowloon. 
Hong Kong, (852) 3-7351223. 

IRELAND: Texas Instruments (Ireland) Limited: 

7/8 Harcourt Street, Stillorgan, County Dublin. Eire, 

1 781677. 

ITALY: Texas Instruments Italia S.p.A. Oivisione 
Semidonduttori: Viale Europa, 40, 2(X)93 Cologne 
Monzese (Milano), (02) 253001; Via Castello della 
Magliana, 38, 00148 Roma, (06) 5222651; 

Via Amendola. 17. 40100 Bologna, (051) 554004. 

JAPAN: Tokyo Marketing/Sales (Headquarters): 

Texas Instruments Japan Ltd., MS Shibaura Bldg., 9F, 
4-13-23 Shibaura, Minato-ku, Tokyo 108. Japan. 
03-769-8700. Texas Instruments Japan Ltd.: Nissho- 
Iwai Bldg. 5F, 30 Imabashi 3-chome. Higashi-ku, 
Osaka 541, Japan, 06-294-1881; Daini Toyota West 
Bldg. 7F, 10-27 Meieki 4-chome, Nakamura-ku, 
Nagoya 450. 052-583-8691; Daiichi Seimei Bldg. 6F. 
3-10 Oyama-cho, Kanazawa 920, Ishikawa-ken, 
0762-23-5471; Daiichi Olympic Tachikawa Bidg. 6F, 

1- 25-12 Akebono-cho. Tachikawa 190, Tokyo, 
0425-27-6426; Matsumoto Showa Bldg. 6F. 2-11 
Fukashi 1-chome, Matsumoto 390, Nagano-ken, 
0263-33-1060; Yokohama Nishiguchi KN Bldg. 6F. 

2- 8-4 Kita-Saiwai-cho, Nishi-ku, Yokohama 220. 
045-322-6741; Nihon Seimei Kyoto Yasaka Bldg. SF, 
843-2 Higashi Shiokohjidori, Nishinotoh-in Higashi-iru, 
Shiokouji, Shimogyo-ku, Kyoto 600, 075-341-7713; 
2597-1, Aza Harudai, Oaza Yasaka, Kitsuki 873, Oita- 
ken, 09786-3-3211; Miho Plant, 2350 Kihara Miho- 
mura, Inashiki-gun 300-04, Ibaragi-ken, 
0298-85-2541. 

KOREA: Texas Instruments Korea Ltd., 28th FI., Trade 
Tower, 59, Samsung-Dong, Kangnam-ku, Seoul, 
Korea 2 ■►551-2810. 

MEXICO: Texas Instruments de Mexico S.A.; Alfonso 
Reyes-115, Col. Hipodromo Condesa, Mexico, D.F.. 
Mexico 06120, 525/525-3860. 

MIDDLE EAST: Texas Instruments: No. 13, 1st Floor 
Mannai Bldg., Diplomatic Area, P.O. Box 26335, 
Manama Bahrain, Arabian Gulf, 973 + 274681. 

NETHERLANDS: Texas Instruments Holland B.V., 

19 Hogehilweg, 1100 AZ Amsterdam—Zuidoost, 
Holland 20 + 5602911. 

NORWAY: Texas Instruments Norway A/S: PB106. 
Refstad 0585, Oslo 5. Norway. (2) 155090. 

PEOPLES REPUBLIC OF CHINA: Texas Instruments 
China Inc., Beijing Representative Office, 7-05 Citic 
Bldg., 19 Jianguomenwai Dajie, Beijing, China, (861) 
5002255, Ext. 3750. 

PHILIPPINES: Texas Instruments Asia Ltd.: 14th Floor. 
Ba- Lepanto Bldg., Paseo de Roxas, Makati, Metro 
Manila, Philippines, 817-60-31. 

PORTUGAL: Texas Instruments Equipamento 
Electronico (Portugal), Lda.: Rua Eng. Frederico Ulrich. 
2650 Moreira Da Maia, 4470 Maia, Portugal, 
2-948-1003. 

SINGAPORE (+ INDIA, INDONESIA, MALAYSIA. 
THAILAND): Texas Instruments Singapore (PTE) Ltd., 
Asia Pacific Division, 101 Thompson Rd. #23-01. 
United Square, Singapore 1130, 350-8100. 

SPAIN: Texas Instruments Espana, S.A.; C/Jose 
Lazaro Galdiano No. 6, Madrid 28036, 1/458.14.58. 

SWEDEN: Texas Instruments International Trade 
Corporation (Sverigefilialen): S-164-93. Stockholm, 
Sweden, 8 - 752-5800. 

SWITZERLAND: Texas Instruments, Inc., Reidstrasae 
6, CH-8953 Dietikon (Zuerich) Switzerland. 

1-740 2220. 

TAIWAN: Texas Instruments Supply Co., 9th Floor 
Bank Tower, 205 Tun Hwa N. Rd., Taipei, Taiwan, 
Republic of China, 2 + 713-9311. 

UNITED KINGDOM: Texas Instruments Limited: 
Manton Lane, Bedford, MK41 7PA, England, 0234 
270111. 
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